Re: [PATCHES] documentation update

On 04.03.2012 18:40, Nis Martensen wrote:
> Please review the attached patches. Most of them simply improve the
> documentation. In a few cases you may want to check whether the new
> documentation is actually correct.

Ok, here are my 5c:

Patches 1, 4 (and others): I don't have much clue about gtk-doc, but these
definitely looks better with the colon. :-)

Patch 6: What exactly is the confusion? Is this fixing a doxygen-ism?

Patch 10: Another instance of "no clue about gtk-doc", but I think it should be
safe to assume you know what you are doing.

> One of the patches (ensure compatibility spelling) also
> adapts code, not sure if this is ok.

I assume this refers to patch 12?

Patch 12: Looks good. Only touches private headers and if the result compiles,
everything is fine...

Patch 13: I don't know anything about quartz, but since lots (all?) other
functions document their error conditions, this should say something about this
case, too.
Also: Whoa, this public function returns NULL on error? Shouldn't this be an
error surface? (Which could count as an API break and thus can't be changed any
more...)

Patch 14: For cairo_raster_source_copy_func_t:
  "@owner: the copy"
I think this should be a little more verbose. However, I don't really know what
this does, either.

Patch 16: This was definitely meant for doxygen.
@Chris: Where did those doxygen comments come from? Was this code copied from
elsewhere?

This series has 22 patches, but the git patch files say "[PATCH xx/25]", where
three patches lost?

> doc/public/cairo-sections.txt still wants an update. I'm not sure
> about the correct sections for the "unused" symbols. Who takes care
> of that?

Good question. Tell me when you figured it out. :-)

TL;DR:
All patches look good to me, I'd merge everything but patches 13 and 14, but
let's first give this a little more time for reviews (or perhaps someone else
shows up and merges these).

Cheers,
Uli
-- 
- He made himself, me nothing, you nothing out of the dust
- Er machte sich mir nichts, dir nichts aus dem Staub
--
cairo mailing list
[email protected]
http://lists.cairographics.org/mailman/listinfo/cairo