[cairo] Some experiments with gtk-doc

[Carl Worth]

On Wed, 26 Jan 2005 18:17:59 -0500, Owen Taylor wrote:
> On a whim I tried using gtk-doc on Cairo, and it, unexpectedly, had
> no problems parsing the headers. So, I spent a bit of time setting
> up the infrastructure and adding some docs, and it worked pretty 
> well:
> 
>  http://fishsoup.net/tmp/cairo-docs/

Owen, thanks for putting in this work. This looks pretty good to me,
(especially if we can get it to generate properly indexed man pages as
well).

The markup within the comments seems quite innocuous, and less invasive
than many other systems to me. This is a priority to me for internal
code. There, the code itself is the primary medium that will be read,
so I really don't want HTML-like tags getting in the way. I'm willing
to give this a try.

As far as documenting the public API, the readability in the source is
much less of an issue. I had argued in the past that that kind of
documentation is better handled outside the code anyway, but it does
look like gtk-doc allows reasonable mixing of external/internal
documentation.

I don't know yet if gtk-doc will handle everything I'd like to throw
at a reference manual, but it seems clear it will help in generating
some initial per-function text. And if our demands grow beyond what
gtk-doc can do, I'll be glad to have it grow to meet them, or just
switch to something else, (such as straight DocBook).

-Carl
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/cairo/attachments/20050127/684ab53b/attachment.pgp