Re: Patches

[Owen Taylor <otaylor redhat com>]

Damon Chaplin <damon ximian com> writes:

> I'd be happy to accept patches to make it prettier, if there was general
> agreement on them.
> 
> Though at some point we may be using the Nautilus help system to view
> the DocBook files directly. I'm not sure what, if any, stylesheet support
> is available there. So you may want to check that before doing much work.
> 
> 
> There are other tasks that you could do for gtk-doc if you want, like
> making it possible to document things like structs/enums/unions/macros
> in the source code files. And making it possible to add the short and long
> section descriptions in the source files as well.

In the context of hacking on gtk-doc, I think the first thing
that needs to be done is to clean up the code at least to
the point of eliminating the large identical sections between
gtkdoc-mktml and gtkdoc-mkhtml.

Havoc made a start at turning the scanning code from gtk-doc into
a nice Perl module with the gtkscan module in GNOME CVS. BUt
I haven't really looked at it much, and it was Havoc's first
Perl module, so I'm not sure the extent o fthe "nice".
 
> So we could eventually get rid of the tmpl/* files and the
> MODULE-sections.txt files altogether. These were originally used so
> I could do all the documentation and organization of sections
> separate from the source code (since the GTK+ developers weren't
> interested in documentation at the time ;-) 

Hey! ;-)

(To explain what Damon already knows, we were plenty interested in
docs, but not particularly in inline docs. Partly, that was some
theoretical misgivings I've since gotten over, partly that was because
I didn't want to make huge changes to the stable GTK+-1.2 source code
to integrate docs.)

> But they have made
> gtk-doc a lot more complicated than it needs to be.
 
I think it is still a little problematical to put section intros
as extensive as section intros should be, with graphics, etc,
into the C files.

After all, C-mode in emacs is a lousy sgml editor....

I would like to see enum and structure docs inline, and that
is actually really easy to do - basically you just need the
extract-docs-from-c-files step to run over the header files
as well, and there you are. I made this change once in
my local copy and it seemed to work fine.

Considerable care needs to be taken in making changes to the
way gtk-doc works as well, in that it's being used in a _lot_
of places now. (The rebuild-docs-scripts on developer.gnome.org
rebuild a good fraction of GNOME.)

> Ideally gtk-doc would just grab all the documentation from the
> source files, maybe do a bit of dynamic querying to get information
> on the hierarchy/signals/args, then output the DocBook. And that
> would be it.

Signal docs would be a problem with this, though properties
in GTK+-2.0 come with doc strings.
 
> Unfortunately I have practically no time to work on gtk-doc myself.

Same here...

Regards,
                                        Owen