[cairo] Re: Documentation

[Russell Shaw]

Carl Worth wrote:
> On Sat, 07 Jan 2006 12:45:50 +1100, Russell Shaw wrote:
> 
>>I spent many hours in making a documentation patch detailing the cairo
>>api and how the porter-duff rendering works, only to have it ignored.
> 
> Hi Russell,
> 
> Is this the patch you're referring to?
> 
> http://lists.freedesktop.org/archives/cairo/2005-August/004915.html
> 
> I apologize for not having responded to it earlier, but frankly it
> looked more like a bug report against gtk-doc with a documentation
> patch attached as a test case, rather than an offer for something to
> be included with cairo's documentation.
> 
> We currently have no real documentation for cairo_operator_t other
> than the names of the operators themselves. What we really need first,
> is good prose descriptions of the operators to guide users in
> selecting an operator based on something they want to do. This could
> describe common uses such as the default OVER for blending potentially
> transparent objects, CLEAR for erasing to transparent, SOURCE for
> copying a source image exactly including any translucence, while
> ignoring the background, DEST_OUT for "cutting a hole" into a picture,
> etc.
> 
> Beyond that, there is a separate need for a separate section with all
> the gory details of cairo's rendering model, with full equations. This
> would not be specific to cairo_operator_t since every rendering
> operation, (cairo_stroke, cairo_fill, cairo_show_glyphs), would need
> to refer to it. The detail in this section should not be necessary for
> "casual" use of cairo, but will be needed for people with particular
> technical needs or morbid curiosity. For example, this section would
> help people implementing new cairo backends, using cairo to implement
> some other graphics system given a similar technical level of detail,
> or performing careful verification of cairo's output, etc.
> 
> The patch you proposed is worded in the style of the more detailed
> section, but really only scratches the surface of what needs to be
> there. Some of that is due to the fact that right up until the cairo
> 1.0 release, some of the fundamental details of cairo's rendering
> model kept changing. For instance, your patch has:
> 
> 	dest = (source OP_IN mask) <OP> dest
> 
> which is valid for describing the operation performed by cairo for some
> cases of <OP> but not for all. The actual equations used are currently
> captured in the code itself, and the rationale is captured in email
> discussions. That's not a useful final resting place for the
> rationale, so I do plan to move that into the detailed section of
> documentation I referred to above when I work on that.
> 
> So there's a high-level explanation of why I didn't commit the
> documentation patch you offered. There are more detailed critiques I
> could offer, but they're not really useful to provide given the
> high-level issues.

Hi,
The main problem with learning an api with little documentation is
that you usually start with a basic step such as getting something
to draw at all, then add on to the understanding incrementally.

It is too big a step to figure out everything enough to submit
any kind of complete document, so *useful* incremental functional
docs that follow the learning curve of the submitter are much
more practical and are easier corrected on the list. All the
incremental docs can eventually be combined into a more detailed
one.

Before being able to learn the internal details of the code, a user
has to learn the external details of how to use the api and how it
works. Only by getting things working at each step, is there
enough motivation to write documentation for newly learnt stuff.
If a user learns everything in a few months, there is much less
motivation to write docs once they know everything, or get distracted
by some other job.

>>When non-existant documentation raises the learning curve to a certain
>>level, it's easier to write your own libs that you can be intimately
>>familiar with and does everything better, faster, and with *far* less
>>but more elegant code.
> 
> Maybe we should each "rm -rf /usr/share/doc" then and start over so we
> can all be intimately familiar with our own better, faster, smaller,
> more elegant code then? I'd better get started. ;-)

It never fealt right to me that thousands of functions are needed
for things like a drawing api or widget kit. By generating a configuration
file with a graphical CAD tool, all the parameters can be parsed by
the toolkit, meaning there's no large api to write or learn.