After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 564644 - Not complete description of the pango_font_description_better_match function
Not complete description of the pango_font_description_better_match function
Status: RESOLVED FIXED
Product: pango
Classification: Platform
Component: docs
1.22.x
Other All
: Normal minor
: ---
Assigned To: pango-maint
pango-maint
Depends on:
Blocks:
 
 
Reported: 2008-12-15 18:08 UTC by Michael Smirnov
Modified: 2008-12-17 14:51 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
patch for changing documentation (650 bytes, patch)
2008-12-15 18:21 UTC, Michael Smirnov
none Details | Review

Description Michael Smirnov 2008-12-15 18:08:53 UTC
Documentation 
Section: http://library.gnome.org/devel/pango/1.22/pango-Fonts.html#pango-font-description-better-match
/**
 * pango_font_description_better_match:
 * @desc: a #PangoFontDescription
 * @old_match: a #PangoFontDescription, or %NULL
 * @new_match: a #PangoFontDescription
 *
 * Determines if the style attributes of @new_match are a closer match
 * for @desc than @old_match, or if @old_match is %NULL, determines if
 * @new_match is a match at all. Approximate matching is done for
 * weight and style; other attributes must match exactly.
 *
 * Return value: %TRUE if @new_match is a better match
 **/

Correct version:
/**
 * pango_font_description_better_match:
 * @desc: a #PangoFontDescription
 * @old_match: a #PangoFontDescription, or %NULL
 * @new_match: a #PangoFontDescription
 *
 * Determines if the style attributes of @new_match are a closer match
 * for @desc than @old_match, or if @old_match is %NULL, determines if
 * @new_match is a match at all. Approximate matching is done for
 * weight and style; other style attributes must match exactly (that
 * does not include family name, size and absoluteness of size).
 *
 * Return value: %TRUE if @new_match is a better match
 **/

Other information:
Comment 1 Behdad Esfahbod 2008-12-15 18:17:19 UTC
Thanks. I fixed with an alternate wording.

2008-12-15  Behdad Esfahbod  <behdad@gnome.org>

        Bug 564644 – Not complete description of the
        pango_font_description_better_match function

        * pango/fonts.c: Improve docs.

Comment 2 Michael Smirnov 2008-12-15 18:21:40 UTC
Created attachment 124746 [details] [review]
patch for changing documentation

Just implemented the changes and made diff.
Comment 3 Michael Smirnov 2008-12-15 19:30:56 UTC
OK, if I got it right there should be a bit more:

/**
 * pango_font_description_better_match:
 * @desc: a #PangoFontDescription
 * @old_match: a #PangoFontDescription, or %NULL
 * @new_match: a #PangoFontDescription
 *
 * Determines if the style attributes of @new_match are a closer match
 * for @desc than @old_match, or if @old_match is %NULL, determines if
 * @new_match is a match at all. Approximate matching is done for
 * weight and style; other style attributes must match exactly (that
 * does not include family name, size and absoluteness of size). Style
 * must be equal for two descriptions to match (PANGO_STYLE_OBLIQUE
 * PANGO_STYLE_ITALIC are considered to be "almost equal": two
 * descriptions will match, but not as good as if there are really
 * equal styles set).
 *
 * Return value: %TRUE if @new_match is a better match
 **/
Comment 4 Behdad Esfahbod 2008-12-15 19:37:57 UTC
Thanks.

2008-12-15  Behdad Esfahbod  <behdad@gnome.org>

        Bug 564644 – Not complete description of the
        pango_font_description_better_match function

        * pango/fonts.c: Improve docs even more.

Comment 5 Owen Taylor 2008-12-15 22:34:09 UTC
I think that description is fine, but I would like to point out
that the whole point of the function was to encapsulate a heuristic
algorithm in an opaque fashion so that it could be changed in one
place if necessary.
Comment 6 Behdad Esfahbod 2008-12-15 22:52:09 UTC
Well, the only changes I made to the docs was:

  1) clarify what "style attributes" means.  I defined them as everything other than family and size-related attributes,

  2) clarify that Oblique and Normal approximately match.

The function is still useful for when we add new attributes (say, when I added gravity).
Comment 7 Michael Smirnov 2008-12-17 14:49:51 UTC
(In reply to comment #5)
> I think that description is fine, but I would like to point out
> that the whole point of the function was to encapsulate a heuristic
> algorithm in an opaque fashion so that it could be changed in one
> place if necessary.
> 

Hello Owen,

I was not saying that "heuristic algorithm in an opaque fashion" is not good. But the documentation of this heuristics was not clear from my point of view.
Comment 8 Michael Smirnov 2008-12-17 14:51:40 UTC
Hi Behdad,

Thank you for fixing the documentation.