[pango/gi-docs: 34/47] docs: Start porting PangoFontMap to the new doc format
- From: Matthias Clasen <matthiasc src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [pango/gi-docs: 34/47] docs: Start porting PangoFontMap to the new doc format
- Date: Wed, 17 Feb 2021 05:28:16 +0000 (UTC)
commit 6fad6bbd173567664bf7a2feca9e20c946d113d5
Author: Matthias Clasen <mclasen redhat com>
Date: Sun Feb 14 23:20:21 2021 -0500
docs: Start porting 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 <stdlib.h>
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
*/
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
