From c8ae084dff887cd6aca622927488e725c392a847 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Mon, 15 Feb 2021 01:17:55 -0500 Subject: docs: Port 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(-) (limited to 'pango') 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) { -- cgit v1.2.1