developer documentation

[Duncan Coutts <duncan coutts worc ox ac uk>]

All,

I just sent this email to Murray who's been looking for ideas for
http://live.gnome.org/IdealDeveloperDocumentation
but I think it might be of interest to other language bindings folks.

So here's my wishlist item:

Annotations (not necessarily user-visible) in the gtk-doc/docbook
documentation to indicate which bits of the docs refer to C'ism, eg
stating the memory ownership semantics of a function etc.

eg:
        "<c-only>Sentance about memory management or some thing else
        that is irrelevant to developers looking at the {insert high
        level programing language here} Gtk+ developer
        documenation.</c-only>"

and for the C docs that would get rendered as just any other ordinary
sentance, but for other language bindings, it'd probabbly get dropped
entirely.

Rationalle:
For the Haskell Gtk+ bindings (http://haskell.org/gtk2hs/) I generate
the Haskell documentation from the gtk-doc docbook xml output. But then
I have to go through afterwards and remove the irrelevant bits that talk
about C-isms. Now, I don't want those completely removed, as they're very
important for me checking that we've done the Haskell bindings correctly
and obviously the C programmers need them. But if we could generate the
majority of the high level language documentation from the C
documentation sources then that would obviusly be a big win for the
language bindings people. And it would allow improvements to the C docs
to propogate into the documentation of the Gtk+ language bindings which
would provide even greater motivation for making it easier to improve
them. It avoids the huge duplication of effort taken on eg by the Gtk#
folk it doing all their own docs. It must be possible to document Gtk+
in a language nutural way (or at least have a recognisable subset that
is language nutural - or contains sufficient markup to automatically
translate for another language binding).

Actually this then leads onto another point. It'd be nice if the gtk-doc
system could be made more friendly for language bindings that want to
generate their own docs from the gtk-doc markup. At the moment, I sort
of reverse engineer the docbook xml output into a sane input xml format
for our Haskell code generator (which outputs code including
documentation in the standard Haddock markup format). So an output
format from gtk-doc that is a simple xml representation of the gtk-doc
comments would be good and make it much easier to generate other
formats. The combination of that and the GObject introspection framework
should make the language bindings sooo much easier to generate &
maintain.

Duncan