[Cairo] format for api docs

[Owen Taylor]

On Mon, 2003-10-13 at 16:44, Carl Worth wrote:
> On Oct 14, Thomas Hunger wrote:
>  > if someone wanted to write some api docs, what would be the best way to do it? 
>  > I like Gtkdoc very much, but a friend of mine said that not all people like 
>  > in-source-documentation.
> 
> I don't think in-source documentation will help Cairo very much.
> 
> The public API, (which is what needs to be documented), is primarily
> contained within a single .h and .c file. There aren't any big object
> trees spread across multiple files/directories, (which is where many
> of the in-source tools help).

That doesn't really match my experience. The advantage of in-source
docs is that it makes the most convenient time to update the docs
the point when you change the code. So, there is no incentive to
put off the documentation to some other time.

Incremental documentation writing also encourages explicit and
extensive documentation that really describes the behavior of the
function; because you are doing it when working on the function,
not when you are thinking "only 43 more functions to go..."

As long as the docs are maintained in parallel with the code, though, it
doesn't really matter too much how it's done. But I've always
found one editor window more convenient than two.

The only reason that I can think of that in-source documentation
would be more useful for larger code bases is that the more functions
you have, the more you appreciate the convenience.

Regards,
					Owen