GNOME Bugzilla – Bug 564644
Not complete description of the pango_font_description_better_match function
Last modified: 2008-12-17 14:51:40 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:
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.
Created attachment 124746 [details] [review] patch for changing documentation Just implemented the changes and made diff.
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 **/
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.
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.
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).
(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.
Hi Behdad, Thank you for fixing the documentation.