[cairo] Suggestion to add some links

[Krzysztof Kosiński]

2010/8/19 Daniel Goldman <dagoldman at yahoo.com>:
> PS - I've been thinking to propose maybe moving from inline source documentation
> (gtk-doc / doxygen) to a wiki. I saw this proposed on a cairo "summer of code"
> page. I would not be in favor of switching to doxygen (if that's the suggestion)
> without strongly considering using a wiki first. I would not be in favor of any
> 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
documentation.

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
source.

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