Re: gtk-docs [was: Updated libgnomecanvas docs]

[Malcolm Tredinnick <malcolm commsecure com au>]

On Fri, May 02, 2003 at 10:00:54AM +0530, Biswapesh Chattopadhyay wrote:
> 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.
> 
> If there is interest in replacing gtk-doc with something more generic
> and extensible, please let me know. SourceBase is pretty small (Glib is
> the only dependency) and the parsers are pretty good (based off source
> navigator). I'm hoping to make a release by the end of this month.

This sounds like quite a nice project, but ...

Will this still require something that is almost as complex as gtk-doc
for the backend? From what you have written above, it sounds like the
backend will need to be able to handle (in the gtk-doc case):

	- understanding the gtk-doc markup format in comments (both in
	  sgml and non-sgml modes).
	- understanding things like the /*< private >*/ comments for
	  fields to leave out of structures.
	- understanding how to merge those comments with the templates
	  to make contents for each page.
	- ordering the function comments according to the contents of
	  *-sections.txt for each module.
	- merging with the other XML files that make up the
	  documentation.

There are probably other things as well. What will not fly is requiring
any of the existing API documentation to change. There are thousands of
lines of it, so the backend would need to be 100% backwards compatible.
All of the items I mentioned above seem to be reasonably peculiar to
gtk-doc in their precise implementation (the ideas are common to other
featureful documentation solutions).

Replacing gtk-doc with something of equal complexity may be just "make
work", unless it possibly improved maintainability. One improvment I can
see from your design is the parsing extraction. So if the backend can
easily get to the point where it is handed a comment that comes before a
public function, then some of the hairier reg-exps from gtk-doc become
redundant.

My personal opinion is that gtk-doc is not too bad. My excuse for not
hacking on it is that it is written in Perl, a language I can read (and
gtk-doc is _readable_ Perl, for the most part) but am really slow at
writing. But it is a nice program. Some of the pattern matching is also
a bit fragile (in terms of the prototypes that they match), so little
errors can have enormous repercussions.

Malcolm

-- 
Always try to be modest and be proud of it!