[cairo] Suggestion to add some links
dagoldman at yahoo.com
Thu Aug 19 10:08:28 PDT 2010
> 2010/8/19 Daniel Goldman <dagoldman at yahoo.com>:
> > PS - I've been thinking to propose maybe moving from inline source
> > (gtk-doc / doxygen) to a wiki. I saw this proposed on a cairo "summer of
> > page. I would not be in favor of switching to doxygen (if that's the
> > without strongly considering using a wiki first. I would not be in favor of
> > change without a lot of thought, because a lot of work would be involved.
> Misleading documentation is worse than no documentation. Having that
> in mind, using a wiki for reference documentation is a very bad idea.
> - After you make changes to the code, you need to go and change X
> pages of the wiki. This is unnecessary overhead. Some people will
> inevitably forget to do it, because it requires you to use a different
> application (text editor vs. browser).
> - What should the wiki describe - the latest stable or the latest dev
> version? In the first case, there would have to be a documentation
> frenzy just after each stable release. In the second, the wiki would
> only be useful for other Cairo developers and people using bleeding
> edge versions. Inline docs don't have this problem, because the docs
> are contained in the commits that introduce new functions or change
> the behavior of existing ones.
> - You send a patch that changes the behavior of some function. When do
> you update the wiki? If you do it right away and your patch is not
> accepted, we end up with misleading documentation. If you do it later,
> it's very likely you'll forget to do it and we end up with misleading
> Inline docs ensure two important things:
> - Every version of the source contains documentation that describes
> the behavior of that particular version of the source.
> - When the behavior of a function changes, the docs change in the same
> commit. There is no moment when the docs are out of sync with the
> Wikis are excellent for tutorials, blueprints, high-level descriptions
> of the concepts used in the code, mathematical theorems underlying the
> operation of the code - things that don't need to closely follow the
> state of the source code. For reference documentation, they are
> dangerously inadequate.
> Regards, Krzysztof
I don't think it's as black and white as you portray. "wiki for reference
documentation is a very bad idea" and "dangerously inadequate" seem like
There are advantages of inline documentation, as you point out. But it goes the
other way too.
http://cairographics.org/summerofcode/ideas/ recommends the same idea of using a
wiki for the reference docs. At least that's how I interpret it. They call it
"easy". I would call it "medium".
To address your points:
*** "Unnecessary overhead" - It is easy to make changes to a wiki. I think most
people are able to handle an editor and a browser. I would call it necessary
*** "Some people will forget" - Some people already are forgetting.
*** "What should wiki describe" - Why not both? If a function is not currently
part of stable version, a note could say so. Or, a note could be added to an
existing function that something new is under development in an existing
*** "Documentation frenzy on new release" - Maybe there might be. Maybe not. I
*** "When do you update wiki after patch" - After patch is accepted. I admit
this is a negative, since the new documentation is included with patch.
*** "docs never out of sync with source" - I agree with this point.
*** "every version of the source contains it's documentation" - Yes. But how
often do people use previous versions of the source? What would be the real
usefulness of this? Good source code should be self-documenting anyway, and
document the intent if not clear from the function or variable name. See "Code
I would add another advantage of inline docs, maybe the biggest one. gtk-doc
creates a great index. To understand cairo, I reviewed just every function and
made my own cheat sheet to make up for some inadequacies in the docs. In that
process, the index has been my best friend. I don't know if the index could be
auto-generated with a wiki.
Another advantage of the inline docs might be uniformity, since it's controlled
by gtk-doc, and by consistent directives. But it currently generates a
sub-optimal layout, which cannot be edited. And sometimes one size does not fit
The current docs are not bad. I would give them a B overall. A few pages are
even exemplary, such as http://cairographics.org/manual/cairo-version-info.html
Here are some problems with the current docs, some of which could be improved
either with wiki or inline docs:
**** "see also" links mostly missing. This is a big gap, and what I miss most.
Every function should have at least a few "see also" links for related or
*** "synopsis" section poorly formatted and hard to read and interpret. It all
runs together. If inline docs retained, at least format this part better.
*** poor explanation of concepts. In reviewing the functions, I found many
ambiguities. I asked about some of these out in previous posts. Another that
comes to mind is "reference count". I would have just edited the wiki, but it's
too awkward to do through editing the inline docs. I could post to this group.
But that's pretty roundabout compared with editing a wiki. Who makes the changes
once there is a consensus on the discussion group? Searching this group helps
clear up ambiguities, but then it's too awkward to edit the inline docs.
Here are some advantages of using a wiki for the API docs:
**** Greatly lowers barrier to editing. It's way too much for many people to
get, edit, and submit the source. It's order of magnitude easier to edit a wiki.
*** Easier to edit. It might be easier to make changes to a wiki than to
remember obscure inline doc directives.
**** WYSIWYG - Changes to the wiki are immediate. How long does it take to see
changes to inline docs? This is like the good old days with submitting a job to
the mainframe job queue and coming back in the next day to see what happened.
**** Allows non-programmers to edit docs. It's well known that most programmers
are poor at documenting their code. And don't know how to write self-documenting
code. Good technical writers are usually not good programmers. And vice versa.
**** Better formatting of API docs - The layout of the docs could be easily
improved with a wiki. Perhaps there is some way to improve the layout of the
current version. I don't know.
**** Serves as discussion. Questions or unresolved issues can be easily inserted
into the wiki text. Others can see and resolve them.
Since there are so many open source projects, I imagine there is already a
consensus about how to write API docs. If the consensus is gtk-doc / doxygen
better than wiki, I'm certainly not going to argue with that.
Anyway, as the post title indicates, the original point was to add a few basic
links to make the cairo web site easier to navigate. I hope that's a no-brainer.
More information about the cairo