diff options
author | Philip Withnall <withnall@endlessm.com> | 2020-02-12 11:06:55 +0000 |
---|---|---|
committer | Ray Strode <halfline@gmail.com> | 2020-02-18 16:02:44 +0000 |
commit | 70009682bca7268cfde00c1fb2fa95b732ed1a43 (patch) | |
tree | d0ae9955bfe26a2afeb0354774731e7d8aa00c75 | |
parent | bd3de96029a5af64b699af8e626d9742d8ba2d69 (diff) |
libaccountsservice: Expand documentation of ActUser:language
In particular, make it clear what format a locale is in, and what the
empty string and NULL values mean. I’ve guessed what they mean based on
what code which uses libaccountsservice does.
Signed-off-by: Philip Withnall <withnall@endlessm.com>
-rw-r--r-- | src/libaccountsservice/act-user.c | 27 |
1 files changed, 23 insertions, 4 deletions
diff --git a/src/libaccountsservice/act-user.c b/src/libaccountsservice/act-user.c index 8c30a02..3752dc7 100644 --- a/src/libaccountsservice/act-user.c +++ b/src/libaccountsservice/act-user.c @@ -379,6 +379,22 @@ act_user_class_init (ActUserClass *class) "The path to an icon for this user.", NULL, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS)); + + /** + * ActUser:language: (nullable) + * + * The user’s locale, in the format + * `language[_territory][.codeset][@modifier]`, where `language` is an + * ISO 639 language code, `territory` is an ISO 3166 country code, and + * `codeset` is a character set or encoding identifier like `ISO-8859-1` + * or `UTF-8`; as specified by [`setlocale(3)`](man:setlocale(3)). + * + * The locale may be the empty string, which means the user is using the + * system default locale. + * + * The property may be %NULL if it wasn’t possible to load it from the + * daemon. + */ g_object_class_install_property (gobject_class, PROP_LANGUAGE, g_param_spec_string ("language", @@ -1011,9 +1027,11 @@ act_user_get_icon_file (ActUser *user) * act_user_get_language: * @user: a #ActUser * - * Returns the path to the configured locale of @user. + * Returns the value of #ActUser:language. * - * Returns: (transfer none): a path to an icon + * Returns: (transfer none) (nullable): the user’s language, or the empty string + * if they are using the system default language, or %NULL if there is no + * connection to the daemon */ const char * act_user_get_language (ActUser *user) @@ -1345,9 +1363,10 @@ act_user_set_email (ActUser *user, /** * act_user_set_language: * @user: the user object to alter. - * @language: a locale (e.g. en_US.utf8) + * @language: (not nullable): a locale (for example, `en_US.utf8`), or the empty + * string to use the system default locale * - * Assigns a new locale for @user. + * Assigns a new locale for @user, setting #ActUser:language. * * Note this function is synchronous and ignores errors. **/ |