Re: more documentation comments

[Owen Taylor <otaylor redhat com>]

Patrick <pabos glypsube org> writes:

> 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? 

PangoFontDescription is a generic structure that is used in many
places; some of them ... e.g. pango_layout_set_font_description
allow a comma-separated list. Others ... e.g. pango_context_load_font()
don't. There is no way of enumerating the places here because 
PangoFontDescription can be used in places that aren't even
in Pango.

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

Put a patch with better wording in bugzilla.gnome.org...

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

Put a patch with better wording in bugzilla.gnome.org ... 
'a collection of font faces' is probably is closer to to the
terminology we currently use.... the use of 'style' to
refer to 'roman/italic/oblique' is confusing, but it is
the CSS terminology, so I felt obliged to be consistent
with it.

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 don't think links to "random" docs on the web is a good idea ... 
just inviting broken links, but I'm sure more explanation of the 
terminology in the docs would help.

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

It's in pango/fonts.c... not sure why your grep missed it.

Is there some way I can review
> the documentation and suggest changes other than by posting every little
> thing to the mailing list 

The appropriate place for bug reports about pango documentation is
bugzilla.gnome.org.

Regards,
                                        Owen