Bug 2798

This is blocking on fixing the --only-section-tmpl of gtk-doc to work.

(Another approach would be to move the section templates inline, but
having large chunks of docbook inline in the C files seems unattractive
to me.)

It's become less of a problem though, as the cairo API stabilizes.

Move bugs against "cvs" version to "0.9.3" so we can remove the "cvs" version.

The docs are not built anymore unless specifically asked for by supplying --enable-gtk-doc *and* make'ing the 'doc' target so this is even less of a problem now.

Also, with git the empty modifications do not seem to bother normal updates.

Since this is more an issue of gtk-doc and not specifically Cairo, and also because it's not in-your-face anymore, I'm closing this as WONTFIX.

Please reopen if you feel this issue still poses significant trouble to Cairo development / building from git.

We do want to move the docs to .c files though.

(In reply to comment #4)
> We do want to move the docs to .c files though.

Or stop using gtk-doc altogether and move all documentation _out_ of the .c files....

-Carl

(In reply to comment #5)
> (In reply to comment #4)
> > We do want to move the docs to .c files though.
> 
> Or stop using gtk-doc altogether and move all documentation _out_ of the .c
> files....

And risk having them all outdated.
 
> -Carl
> 

(In reply to comment #6)
> And risk having them all outdated.

I don't buy that argument at all.

What's necessary is a culture that mandates that a change or addition
to the semantics of the library be accompanied with an update to the
documentation at the same time. I think we have that culture within
the cairo community now.

Something that helps that culture is a tool that allows a single
"commit" to show both changes to the code and changes to the
documentation as atomic. So that feature I would definitely like. But
I don't think that has anything to do with "documentation in .c
files".

And something that we've been entirely missing out on with the
documentation is a conversation with users of the library/consumers of
the documentation. These are people that might never need to look at
the implementation of cairo, but do very often read the documentation
and are the people most acutely aware of problems in that
documentation.

So I really want to move the documentation to "live" in something like
a wiki, where there is at least a "discuss" page where users can
freely comment on things that were unclear in the documentation, or
things they've learned elsewhere that should be added, etc.

I'll talk more about this on the mailing list soon.

-Carl