GNOME IDL documentation.

[Rich Burridge <Rich Burridge Sun COM>]

Hi all,

About a week ago, I asked:

  Are you (or is anyone else) interested in doing some more work with
  the gtk-doc PERL scripts?  I'm part of a group of people that have
  been putting together a proposed API for GNOME Speech v1.0. This API
  is heavily influenced by the Java Speech API which has extensive JavaDoc
  comments. We have used this to add extensive IDL style comments to the 
  IDL files.
  
Biswapesh Chattopadhyay replied:
  I've been working on SourceBase (http://sourcebase.sf.net/) which is a
  generic parser library with support for pluggable storage backends and
  parsers. The current set of parsers include C, C++, Java, M4, Python,
  etc. The significant thing is that the parsers can handle comments,
  cross-freference, inheritence and other goodies, so it should be pretty
  easy to do everything Doxygen, gtk-doc, etc. can with a bit of effort.

Unfortunately sourcebase doesn't currently handle IDL parsing, so I 
continued my search and came across Synopsis at:

  http://synopsis.sf.net

This supports my IDL requirements. It also has parsers for other languages
(C++, Python), and can generate documentation in

 HTML - takes a directory name for output (-o Directory)
        Creates many pages in that directory
 HTML_Simple - one-page HTML output
 Dia - generates a Dia file with classes and generalizations
 Dot - generates various graphs, such as Inheritance
 DocBook - generates a docbook file
 BoostBook - generates a boostbook file (not complete)
 ASCII - Tries to output the AST in a way that is syntactically valid as
         input.
 DUMP - Dumps the AST in a verbose form. This is useful only if you are
        trying to figure out how various input is converted to AST objects.
        Pipe into "less -r" for best results.

For IDL parsing, it uses the omniidl IDL parser which is part of the 
omniorb distribution at:

  http://omniorb.sourceforge.net

and can optionally use Graphviz for generating graphical relationships in 
the output documentation. The graphviz distribution is at:

  http:://www.graphviz.org
  
Even though their last .tar.gz release was a couple years ago, it's being
actively developed in CVS. As I tried to get this work, the developers
were extremely helpful.

If we are looking for a GNOME documentation package that goes beyond what
gtk-doc can currently support, then we might want to consider this combo.

Certainly one of the easier this to do, for somebody who understands the
gtk-doc style (tags etc), would be to add a gtk-doc parser to their set
of supported parsers.