more documentation comments

[Patrick <pabos glypsube org>]

QUOTE:
"
pango_font_description_set_family ()

void        pango_font_description_set_family
                                            (PangoFontDescription *desc,
                                             const char *family);

Sets the family name field of a font description. The family name
represents a family of related font styles, and will resolve to a
particular PangoFontFamily. In some uses of PangoFontDescription, it is
also possible to use a comma separated list of family names for this
field.
"

What does the "in some uses of" comment refer to? ie. when used to find
a font it can be a comma seperated list and when its returned as a part
of a list of fonts its not comma separated? i think this should be made
more explicit or removed since reading something to the effect of "other
things can be also be done" and then not explaining them is very
annoying. Also, the definition of a font family is somewhat unclear
(strictly according to the docs) since "a collection of font styles" is
not defined anywhere else that I noticed and
pango_font_description_set_style is only one field of a font
description. A pointer to something like:
http://freetype.sourceforge.net/freetype2/docs/glyphs/glyphs-1.html#section-1
which tries to explain font terminology might be useful to place
somewhere in the preamble to the "Fonts" section.

I was under the impression that the API docs were generated from the
source somehow. However, doing a grep -r "in some uses" * in a copy of
the Pango source doesn't return anything. Is there some way I can review
the documentation and suggest changes other than by posting every little
thing to the mailing list (and similarly for the aging pango.org website
which redirects everywhere but itself)?

---
Patrick