Re: [gtkmm] Reusing gtk+ reference documentation

[James Henstridge <james daa com au>]

Murray Cumming wrote:

> On Sat, 2001-12-01 at 23:58, Murray Cumming wrote:
>
> > My current plan was to copy all the gtk+ inline documentation to gtkmm2
> > when they seemed to have finished writing it themselves.
> >
> > However, maybe this would work:
> >
> > - A script could scan all the gtk+ code, outputting the text in to a
> > file that's a bit like gtk.defs. For instance, gtk.refdoc gtk-doc must
> > already do similar scanning to build the html.
> >
> > - gtkmmproc would look at this gtk.refdoc file as well as gtk.defs when
> > it builds the .h/.cc files. It would put the gtk+ comments next to our
> > gtkmm methods, for Doxygen to parse. This would make gtkmmproc even
> > slower, of course.
> >
> > - The gtk+ documentation would not always be appropriate, so we could
> > have a second file containing a few custom overrides. gtkmmproc would
> > use the custom text if it exists for the method.
> >
> > This would allow us to reuse the code without a lot of tedious
> > copy-and-paste, and it would allow us to update our documentation when
> > gtk+ updates theirs.
>
> Would any perl coders like to take this task on? I think that the best way might be to add a 
> --output-docs-defs option to the gtkdoc-mkdb script in the gtk-doc
> module. We could then add a suitable make target where this is used in
> gtk/docs/reference.
You might want to look at the docgen.py script in the codegen/ 
subdirectory of pygtk.  It uses a defs file to get information about how 
the C API maps to methods of objects, then pulls the documentation out 
of the source code and outputs fake python documentation :)

The script is a little out of date now because of the big class renaming 
I did in pygtk, but the script might be useful to you.

You will still need some form of language dependent overrides, as some 
of the inline docs are C specific (one or two include C example code).

James.

--
Email: james daa com au
WWW:   http://www.daa.com.au/~james/