From ec41c7fbb14b8cad24a9fb7f2eb095bc8d669a89 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sun, 14 Feb 2021 23:20:21 -0500 Subject: docs: Port PangoFontMap to the new doc format Replace gtk-doc'isms and use gi-docgen links instead. --- pango/pango-fontmap.c | 193 +++++++++++++++++++++++++------------------------- 1 file changed, 97 insertions(+), 96 deletions(-) diff --git a/pango/pango-fontmap.c b/pango/pango-fontmap.c index 3360b1ee..ab9c816d 100644 --- a/pango/pango-fontmap.c +++ b/pango/pango-fontmap.c @@ -10,7 +10,7 @@ * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Library General Public License for more details. * * You should have received a copy of the GNU Library General Public @@ -29,9 +29,9 @@ #include static PangoFontset *pango_font_map_real_load_fontset (PangoFontMap *fontmap, - PangoContext *context, - const PangoFontDescription *desc, - PangoLanguage *language); + PangoContext *context, + const PangoFontDescription *desc, + PangoLanguage *language); static PangoFontFamily *pango_font_map_real_get_family (PangoFontMap *fontmap, @@ -64,21 +64,23 @@ pango_font_map_init (PangoFontMap *fontmap G_GNUC_UNUSED) /** * pango_font_map_create_context: - * @fontmap: a #PangoFontMap + * @fontmap: a `PangoFontMap` * - * Creates a #PangoContext connected to @fontmap. This is equivalent - * to pango_context_new() followed by pango_context_set_font_map(). + * Creates a `PangoContext` connected to @fontmap. + * + * This is equivalent to [method@Pango.Context.new] followed by + * [method@Pango.Context.set_font_map]. * * If you are using Pango as part of a higher-level system, - * that system may have it's own way of create a #PangoContext. - * For instance, the GTK+ toolkit has, among others, + * that system may have it's own way of create a `PangoContext`. + * For instance, the GTK toolkit has, among others, * gtk_widget_get_pango_context(). Use those instead. * - * Return value: (transfer full): the newly allocated #PangoContext, - * which should be freed with g_object_unref(). + * Return value: (transfer full): the newly allocated `PangoContext`, + * which should be freed with g_object_unref(). * * Since: 1.22 - **/ + */ PangoContext * pango_font_map_create_context (PangoFontMap *fontmap) { @@ -94,19 +96,19 @@ pango_font_map_create_context (PangoFontMap *fontmap) /** * pango_font_map_load_font: - * @fontmap: a #PangoFontMap - * @context: the #PangoContext the font will be used with - * @desc: a #PangoFontDescription describing the font to load + * @fontmap: a `PangoFontMap` + * @context: the `PangoContext` the font will be used with + * @desc: a `PangoFontDescription` describing the font to load * * Load the font in the fontmap that is the closest match for @desc. * - * Returns: (transfer full) (nullable): the newly allocated #PangoFont - * loaded, or %NULL if no font matched. - **/ + * Returns: (transfer full) (nullable): the newly allocated `PangoFont` + * loaded, or %NULL if no font matched. + */ PangoFont * pango_font_map_load_font (PangoFontMap *fontmap, - PangoContext *context, - const PangoFontDescription *desc) + PangoContext *context, + const PangoFontDescription *desc) { g_return_val_if_fail (fontmap != NULL, NULL); @@ -115,45 +117,45 @@ pango_font_map_load_font (PangoFontMap *fontmap, /** * pango_font_map_list_families: - * @fontmap: a #PangoFontMap - * @families: (out) (array length=n_families) (transfer container): location to store a pointer to an array of #PangoFontFamily *. + * @fontmap: a `PangoFontMap` + * @families: (out) (array length=n_families) (transfer container): location to store a pointer to an array of `PangoFontFamily` *. * This array should be freed with g_free(). * @n_families: (out): location to store the number of elements in @families * * List all families for a fontmap. - **/ + */ void pango_font_map_list_families (PangoFontMap *fontmap, - PangoFontFamily ***families, - int *n_families) + PangoFontFamily ***families, + int *n_families) { PangoFontMapPrivate *priv = pango_font_map_get_instance_private (fontmap); g_return_if_fail (fontmap != NULL); PANGO_FONT_MAP_GET_CLASS (fontmap)->list_families (fontmap, families, n_families); - + /* keep this value for GListModel::changed */ priv->n_families = *n_families; } /** * pango_font_map_load_fontset: - * @fontmap: a #PangoFontMap - * @context: the #PangoContext the font will be used with - * @desc: a #PangoFontDescription describing the font to load - * @language: a #PangoLanguage the fonts will be used for + * @fontmap: a `PangoFontMap` + * @context: the `PangoContext` the font will be used with + * @desc: a `PangoFontDescription` describing the font to load + * @language: a `PangoLanguage` the fonts will be used for * * Load a set of fonts in the fontmap that can be used to render * a font matching @desc. * * Returns: (transfer full) (nullable): the newly allocated - * #PangoFontset loaded, or %NULL if no font matched. - **/ + * `PangoFontset` loaded, or %NULL if no font matched. + */ PangoFontset * -pango_font_map_load_fontset (PangoFontMap *fontmap, - PangoContext *context, - const PangoFontDescription *desc, - PangoLanguage *language) +pango_font_map_load_fontset (PangoFontMap *fontmap, + PangoContext *context, + const PangoFontDescription *desc, + PangoLanguage *language) { g_return_val_if_fail (fontmap != NULL, NULL); @@ -162,10 +164,10 @@ pango_font_map_load_fontset (PangoFontMap *fontmap, static void pango_font_map_fontset_add_fonts (PangoFontMap *fontmap, - PangoContext *context, - PangoFontsetSimple *fonts, - PangoFontDescription *desc, - const char *family) + PangoContext *context, + PangoFontsetSimple *fonts, + PangoFontDescription *desc, + const char *family) { PangoFont *font; @@ -177,9 +179,9 @@ pango_font_map_fontset_add_fonts (PangoFontMap *fontmap, static PangoFontset * pango_font_map_real_load_fontset (PangoFontMap *fontmap, - PangoContext *context, - const PangoFontDescription *desc, - PangoLanguage *language) + PangoContext *context, + const PangoFontDescription *desc, + PangoLanguage *language) { PangoFontDescription *tmp_desc = pango_font_description_copy_static (desc); const char *family; @@ -196,10 +198,10 @@ pango_font_map_real_load_fontset (PangoFontMap *fontmap, for (i = 0; families[i]; i++) pango_font_map_fontset_add_fonts (fontmap, - context, - fonts, - tmp_desc, - families[i]); + context, + fonts, + tmp_desc, + families[i]); g_strfreev (families); @@ -211,32 +213,32 @@ pango_font_map_real_load_fontset (PangoFontMap *fontmap, char *ctmp1, *ctmp2; pango_font_description_set_family_static (tmp_desc, - pango_font_description_get_family (desc)); + pango_font_description_get_family (desc)); ctmp1 = pango_font_description_to_string (desc); pango_font_description_set_family_static (tmp_desc, "Sans"); G_LOCK (warned_fonts); if (!warned_fonts || !g_hash_table_lookup (warned_fonts, ctmp1)) - { - if (!warned_fonts) - warned_fonts = g_hash_table_new (g_str_hash, g_str_equal); + { + if (!warned_fonts) + warned_fonts = g_hash_table_new (g_str_hash, g_str_equal); - g_hash_table_insert (warned_fonts, g_strdup (ctmp1), GINT_TO_POINTER (1)); + g_hash_table_insert (warned_fonts, g_strdup (ctmp1), GINT_TO_POINTER (1)); - ctmp2 = pango_font_description_to_string (tmp_desc); - g_warning ("couldn't load font \"%s\", falling back to \"%s\", " - "expect ugly output.", ctmp1, ctmp2); - g_free (ctmp2); - } + ctmp2 = pango_font_description_to_string (tmp_desc); + g_warning ("couldn't load font \"%s\", falling back to \"%s\", " + "expect ugly output.", ctmp1, ctmp2); + g_free (ctmp2); + } G_UNLOCK (warned_fonts); g_free (ctmp1); pango_font_map_fontset_add_fonts (fontmap, - context, - fonts, - tmp_desc, - "Sans"); + context, + fonts, + tmp_desc, + "Sans"); } /* We couldn't try with Sans and the specified style. Try Sans Normal @@ -254,23 +256,23 @@ pango_font_map_real_load_fontset (PangoFontMap *fontmap, G_LOCK (warned_fonts); if (!warned_fonts || !g_hash_table_lookup (warned_fonts, ctmp1)) - { - g_hash_table_insert (warned_fonts, g_strdup (ctmp1), GINT_TO_POINTER (1)); + { + g_hash_table_insert (warned_fonts, g_strdup (ctmp1), GINT_TO_POINTER (1)); - ctmp2 = pango_font_description_to_string (tmp_desc); + ctmp2 = pango_font_description_to_string (tmp_desc); - g_warning ("couldn't load font \"%s\", falling back to \"%s\", " - "expect ugly output.", ctmp1, ctmp2); - g_free (ctmp2); - } + g_warning ("couldn't load font \"%s\", falling back to \"%s\", " + "expect ugly output.", ctmp1, ctmp2); + g_free (ctmp2); + } G_UNLOCK (warned_fonts); g_free (ctmp1); pango_font_map_fontset_add_fonts (fontmap, - context, - fonts, - tmp_desc, - "Sans"); + context, + fonts, + tmp_desc, + "Sans"); } pango_font_description_free (tmp_desc); @@ -286,19 +288,17 @@ pango_font_map_real_load_fontset (PangoFontMap *fontmap, /** * pango_font_map_get_shape_engine_type: - * @fontmap: a #PangoFontMap + * @fontmap: a `PangoFontMap` * * Returns the render ID for shape engines for this fontmap. - * See the `render_type` field of - * #PangoEngineInfo. + * See the `render_type` field of #PangoEngineInfo. * - * Return value: the ID string for shape engines for - * this fontmap. Owned by Pango, should not be modified - * or freed. + * Return value: the ID string for shape engines for this fontmap. + * Owned by Pango, should not be modified or freed. * * Since: 1.4 * Deprecated: 1.38 - **/ + */ const char * pango_font_map_get_shape_engine_type (PangoFontMap *fontmap) { @@ -309,24 +309,25 @@ pango_font_map_get_shape_engine_type (PangoFontMap *fontmap) /** * pango_font_map_get_serial: - * @fontmap: a #PangoFontMap + * @fontmap: a `PangoFontMap` * - * Returns the current serial number of @fontmap. The serial number is - * initialized to an small number larger than zero when a new fontmap - * is created and is increased whenever the fontmap is changed. It may - * wrap, but will never have the value 0. Since it can wrap, never compare - * it with "less than", always use "not equals". + * Returns the current serial number of @fontmap. + * + * The serial number is initialized to an small number larger than zero + * when a new fontmap is created and is increased whenever the fontmap + * is changed. It may wrap, but will never have the value 0. Since it can + * wrap, never compare it with "less than", always use "not equals". * * The fontmap can only be changed using backend-specific API, like changing * fontmap resolution. * - * This can be used to automatically detect changes to a #PangoFontMap, like - * in #PangoContext. + * This can be used to automatically detect changes to a `PangoFontMap`, + * like in `PangoContext`. * * Return value: The current serial number of @fontmap. * * Since: 1.32.4 - **/ + */ guint pango_font_map_get_serial (PangoFontMap *fontmap) { @@ -347,23 +348,23 @@ pango_font_map_real_changed (PangoFontMap *fontmap) removed = priv->n_families; added = g_list_model_get_n_items (G_LIST_MODEL (fontmap)); - g_list_model_items_changed (G_LIST_MODEL (fontmap), 0, removed, added); + g_list_model_items_changed (G_LIST_MODEL (fontmap), 0, removed, added); } /** * pango_font_map_changed: - * @fontmap: a #PangoFontMap + * @fontmap: a `PangoFontMap` * - * Forces a change in the context, which will cause any #PangoContext + * Forces a change in the context, which will cause any `PangoContext` * using this fontmap to change. * * This function is only useful when implementing a new backend * for Pango, something applications won't do. Backends should - * call this function if they have attached extra data to the context - * and such data is changed. + * call this function if they have attached extra data to the + * context and such data is changed. * * Since: 1.34 - **/ + */ void pango_font_map_changed (PangoFontMap *fontmap) { @@ -402,12 +403,12 @@ pango_font_map_real_get_family (PangoFontMap *fontmap, /** * pango_font_map_get_family: - * @fontmap: a #PangoFontMap + * @fontmap: a `PangoFontMap` * @name: a family name * * Gets a font family by name. * - * Returns: (transfer none): the #PangoFontFamily + * Returns: (transfer none): the `PangoFontFamily` * * Since: 1.46 */ -- cgit v1.2.1