GNOME.org
 

[pango/gi-docs: 37/47] docs: Start porting PangoLanguage to the new doc format


commit 397ca546f666b2cf1f767afe3697ac1f296c6667
Author: Matthias Clasen <mclasen redhat com>
Date:   Mon Feb 15 01:17:55 2021 -0500

    docs: Start porting PangoLanguage to the new doc format
    
    Replace gtk-doc'isms and use gi-docgen links instead.

 pango/pango-language.c | 132 ++++++++++++++++++++++++-------------------------
 1 file changed, 65 insertions(+), 67 deletions(-)
---
diff --git a/pango/pango-language.c b/pango/pango-language.c
index 42279c98..7ce052b4 100644
--- a/pango/pango-language.c
+++ b/pango/pango-language.c
@@ -136,10 +136,10 @@ pango_language_free (PangoLanguage *language G_GNUC_UNUSED)
 /**
  * PangoLanguage:
  *
- * The #PangoLanguage structure is used to
+ * The `PangoLanguage` structure is used to
  * represent a language.
  *
- * #PangoLanguage pointers can be efficiently
+ * `PangoLanguage` pointers can be efficiently
  * copied and compared with each other.
  */
 G_DEFINE_BOXED_TYPE (PangoLanguage, pango_language,
@@ -251,7 +251,7 @@ _pango_get_lc_ctype (void)
 /**
  * pango_language_get_default:
  *
- * Returns the #PangoLanguage for the current locale of the process.
+ * Returns the `PangoLanguage` for the current locale of the process.
  * Note that this can change over the life of an application.
  *
  * On Unix systems, this is the return value is derived from
@@ -276,10 +276,10 @@ _pango_get_lc_ctype (void)
  * Your application should call `setlocale(LC_ALL, "")` for the user
  * settings to take effect. GTK does this in its initialization
  * functions automatically (by calling gtk_set_locale()).
- * See the setlocale manpage for more details.
+ * See the setlocale() manpage for more details.
  *
  * Return value: (transfer none): the default language as a
- *               #PangoLanguage, must not be freed.
+ *               `PangoLanguage`, must not be freed.
  *
  * Since: 1.16
  **/
@@ -308,7 +308,7 @@ pango_language_get_default (void)
  * @language: (allow-none): a string representing a language tag, or %NULL
  *
  * Take a RFC-3066 format language tag as a string and convert it to a
- * #PangoLanguage pointer that can be efficiently copied (copy the
+ * `PangoLanguage` pointer that can be efficiently copied (copy the
  * pointer) and compared with other language tags (compare the
  * pointer.)
  *
@@ -316,14 +316,13 @@ pango_language_get_default (void)
  * lowercase, mapping '_' to '-', and stripping all characters other
  * than letters and '-'.
  *
- * Use pango_language_get_default() if you want to get the #PangoLanguage for
- * the current locale of the process.
+ * Use [func@language_get_default] if you want to get the `PangoLanguage`
+ * for the current locale of the process.
  *
  * Return value: (transfer none) (nullable): an opaque pointer to a
- *               #PangoLanguage structure, or %NULL if @language was
- *               %NULL.  The returned pointer will be valid forever
- *               after, and should not be freed.
- **/
+ *   `PangoLanguage` structure, or %NULL if @language was %NULL. The
+ *   returned pointer will be valid forever after, and should not be freed.
+ */
 PangoLanguage *
 pango_language_from_string (const char *language)
 {
@@ -373,10 +372,10 @@ out:
  * pango_language_to_string:
  * @language: a language tag.
  *
- * Gets the RFC-3066 format string representing the given language tag. 
+ * Gets the RFC-3066 format string representing the given language tag.
  *
- * Returns: a string representing the language tag.  This is owned by
- *          Pango and should not be freed.
+ * Returns: a string representing the language tag. This is owned by
+ *   Pango and should not be freed.
  */
 const char *
 (pango_language_to_string) (PangoLanguage *language)
@@ -386,12 +385,12 @@ const char *
 
 /**
  * pango_language_matches:
- * @language: (nullable): a language tag (see pango_language_from_string()),
- *            %NULL is allowed and matches nothing but '*'
+ * @language: (nullable): a language tag (see [func@language_from_string]),
+ *   %NULL is allowed and matches nothing but '*'
  * @range_list: a list of language ranges, separated by ';', ':',
  *   ',', or space characters.
  *   Each element must either be '*', or a RFC 3066 language range
- *   canonicalized as by pango_language_from_string()
+ *   canonicalized as by [func@language_from_string]
  *
  * Checks if a language tag matches one of the elements in a list of
  * language ranges. A language tag is considered to match a range
@@ -400,7 +399,7 @@ const char *
  * in the tag is '-'.
  *
  * Return value: %TRUE if a match was found.
- **/
+ */
 gboolean
 pango_language_matches (PangoLanguage *language,
                        const char    *range_list)
@@ -560,18 +559,18 @@ static const LangInfo lang_texts[] = {
 
 /**
  * pango_language_get_sample_string:
- * @language: (nullable): a #PangoLanguage, or %NULL
+ * @language: (nullable): a `PangoLanguage`, or %NULL
  *
  * Get a string that is representative of the characters needed to
  * render a particular language.
  *
- * The sample text may be a pangram, but is not necessarily.  It is chosen to
- * be demonstrative of normal text in the language, as well as exposing font
- * feature requirements unique to the language.  It is suitable for use
+ * The sample text may be a pangram, but is not necessarily. It is chosen
+ * to be demonstrative of normal text in the language, as well as exposing
+ * font feature requirements unique to the language. It is suitable for use
  * as sample text in a font selection dialog.
  *
  * If @language is %NULL, the default language as found by
- * pango_language_get_default() is used.
+ * [func@language_get_default] is used.
  *
  * If Pango does not have a sample string for @language, the classic
  * "The quick brown fox..." is returned.  This can be detected by
@@ -584,7 +583,7 @@ static const LangInfo lang_texts[] = {
  *
  * Return value: the sample string. This value is owned by Pango
  *   and should not be freed.
- **/
+ */
 const char *
 pango_language_get_sample_string (PangoLanguage *language)
 {
@@ -615,9 +614,9 @@ pango_language_get_sample_string (PangoLanguage *language)
 
 /**
  * pango_language_get_scripts:
- * @language: (allow-none): a #PangoLanguage, or %NULL
- * @num_scripts: (out caller-allocates) (allow-none): location to return number of scripts,
- *            or %NULL
+ * @language: (allow-none): a `PangoLanguage`, or %NULL
+ * @num_scripts: (out caller-allocates) (allow-none): location to
+ *   return number of scripts, or %NULL
  *
  * Determines the scripts used to to write @language.
  * If nothing is known about the language tag @language,
@@ -630,27 +629,27 @@ pango_language_get_sample_string (PangoLanguage *language)
  *
  * Most languages use only one script for writing, but there are
  * some that use two (Latin and Cyrillic for example), and a few
- * use three (Japanese for example).  Applications should not make
+ * use three (Japanese for example). Applications should not make
  * any assumptions on the maximum number of scripts returned
  * though, except that it is positive if the return value is not
  * %NULL, and it is a small number.
  *
- * The pango_language_includes_script() function uses this function
+ * The [func@language_includes_script] function uses this function
  * internally.
  *
- * Note: while the return value is declared as PangoScript, the
- * returned values are from the GUnicodeScript enumeration, which
+ * Note: while the return value is declared as `PangoScript`, the
+ * returned values are from the `GUnicodeScript` enumeration, which
  * may have more values. Callers need to handle unknown values.
  *
  * Return value: (array length=num_scripts) (nullable): An array of
- * #PangoScript values, with the number of entries in the array stored
- * in @num_scripts, or %NULL if Pango does not have any information
- * about this particular language tag (also the case if @language is
- * %NULL).  The returned array is owned by Pango and should not be
- * modified or freed.
- 
+ *   `PangoScript` values, with the number of entries in the array
+ *   stored in @num_scripts, or %NULL if Pango does not have any
+ *   information about this particular language tag (also the case
+ *   if @language is %NULL). The returned array is owned by Pango
+ *   and should not be modified or freed.
+ *
  * Since: 1.22
- **/
+ */
 const PangoScript *
 pango_language_get_scripts (PangoLanguage *language,
                            int           *num_scripts)
@@ -686,8 +685,8 @@ pango_language_get_scripts (PangoLanguage *language,
 
 /**
  * pango_language_includes_script:
- * @language: (nullable): a #PangoLanguage, or %NULL
- * @script: a #PangoScript
+ * @language: (nullable): a `PangoLanguage`, or %NULL
+ * @script: a `PangoScript`
  *
  * Determines if @script is one of the scripts used to
  * write @language. The returned value is conservative;
@@ -697,18 +696,17 @@ pango_language_get_scripts (PangoLanguage *language,
  *
  * This routine is used in Pango's itemization process when
  * determining if a supplied language tag is relevant to
- * a particular section of text. It probably is not useful for
- * applications in most circumstances.
+ * a particular section of text. It probably is not useful
+ * for applications in most circumstances.
  *
- * This function uses pango_language_get_scripts() internally.
+ * This function uses [func@language_get_scripts] internally.
  *
  * Return value: %TRUE if @script is one of the scripts used
- * to write @language or if nothing is known about @language
- * (including the case that @language is %NULL),
- * %FALSE otherwise.
- 
+ *   to write @language or if nothing is known about @language
+ *   (including the case that @language is %NULL), %FALSE otherwise.
+ *
  * Since: 1.4
- **/
+ */
 gboolean
 pango_language_includes_script (PangoLanguage *language,
                                PangoScript    script)
@@ -839,17 +837,17 @@ out:
  * pango_language_get_preferred:
  *
  * Returns the list of languages that the user prefers, as specified
- * by the PANGO_LANGUAGE or LANGUAGE environment variables, in order
+ * by the `PANGO_LANGUAGE` or `LANGUAGE` environment variables, in order
  * of preference. Note that this list does not necessarily include
- * the language returned by pango_language_get_default().
+ * the language returned by [func@language_get_default].
  *
  * When choosing language-specific resources, such as the sample
- * text returned by pango_language_get_sample_string(), you should
+ * text returned by [func@language_get_sample_string], you should
  * first try the default language, followed by the languages returned
  * by this function.
  *
  * Returns: (transfer none) (nullable): a %NULL-terminated array of
- *    PangoLanguage*
+ *   `PangoLanguage`*
  *
  * Since: 1.48
  */
@@ -864,43 +862,43 @@ pango_language_get_preferred (void)
 
 /**
  * pango_script_get_sample_language:
- * @script: a #PangoScript
+ * @script: a `PangoScript`
  *
  * Given a script, finds a language tag that is reasonably
  * representative of that script. This will usually be the
  * most widely spoken or used language written in that script:
  * for instance, the sample language for %PANGO_SCRIPT_CYRILLIC
- * is ru (Russian), the sample language for %PANGO_SCRIPT_ARABIC is ar.
+ * is ru (Russian), the sample language for %PANGO_SCRIPT_ARABIC
+ * is ar.
  *
- * For some
- * scripts, no sample language will be returned because there
- * is no language that is sufficiently representative. The best
- * example of this is %PANGO_SCRIPT_HAN, where various different
+ * For some scripts, no sample language will be returned because
+ * there is no language that is sufficiently representative. The
+ * best example of this is %PANGO_SCRIPT_HAN, where various different
  * variants of written Chinese, Japanese, and Korean all use
  * significantly different sets of Han characters and forms
  * of shared characters. No sample language can be provided
  * for many historical scripts as well.
  *
  * As of 1.18, this function checks the environment variables
- * PANGO_LANGUAGE and LANGUAGE (checked in that order) first.
+ * `PANGO_LANGUAGE` and `LANGUAGE` (checked in that order) first.
  * If one of them is set, it is parsed as a list of language tags
- * separated by colons or other separators.  This function
+ * separated by colons or other separators. This function
  * will return the first language in the parsed list that Pango
- * believes may use @script for writing.  This last predicate
- * is tested using pango_language_includes_script().  This can
+ * believes may use @script for writing. This last predicate
+ * is tested using [func@language_includes_script]. This can
  * be used to control Pango's font selection for non-primary
- * languages.  For example, a PANGO_LANGUAGE enviroment variable
+ * languages. For example, a `PANGO_LANGUAGE` enviroment variable
  * set to "en:fa" makes Pango choose fonts suitable for Persian (fa)
  * instead of Arabic (ar) when a segment of Arabic text is found
- * in an otherwise non-Arabic text.  The same trick can be used to
+ * in an otherwise non-Arabic text. The same trick can be used to
  * choose a default language for %PANGO_SCRIPT_HAN when setting
  * context language is not feasible.
  *
- * Return value: (nullable): a #PangoLanguage that is representative
+ * Return value: (nullable): a `PangoLanguage` that is representative
  * of the script, or %NULL if no such language exists.
  *
  * Since: 1.4
- **/
+ */
 PangoLanguage *
 pango_script_get_sample_language (PangoScript script)
 {
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]