From b766db0878ae686032f73e0c96571dae58595d66 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Wed, 5 Feb 2014 22:49:54 -0500 Subject: [PATCH] Docs: don't use option tags --- glib/docs.c | 6 +++--- glib/ggettext.c | 8 ++++---- glib/goption.c | 59 +++++++++++++++++++++++++------------------------------ glib/gtestutils.c | 30 +++++++++++++--------------- 4 files changed, 48 insertions(+), 55 deletions(-) diff --git a/glib/docs.c b/glib/docs.c index fdc9216..d106bc5 100644 --- a/glib/docs.c +++ b/glib/docs.c @@ -1859,7 +1859,7 @@ * * Expands to __extension__ when gcc is used as the compiler. This simply * tells gcc not to warn about the following non-standard code when compiling - * with the option. + * with the `-pedantic` option. */ /** @@ -1950,7 +1950,7 @@ * * Expands to the GNU C deprecated attribute if the compiler is gcc. * It can be used to mark typedefs, variables and functions as deprecated. - * When called with the option, + * When called with the `-Wdeprecated-declarations` option, * gcc will generate warnings when deprecated interfaces are used. * * Place the attribute after the declaration, just before the semicolon. @@ -2199,7 +2199,7 @@ * Expands to the GNU C no_instrument_function function attribute if the * compiler is gcc. Functions with this attribute will not be instrumented * for profiling, when the compiler is called with the - * option. + * `-finstrument-functions` option. * * Place the attribute after the declaration, just before the semicolon. * diff --git a/glib/ggettext.c b/glib/ggettext.c index 2c27441..a24e885 100644 --- a/glib/ggettext.c +++ b/glib/ggettext.c @@ -523,9 +523,9 @@ g_dngettext (const gchar *domain, * with context. * * If you are using the Q_() macro, you need to make sure that you pass - * to xgettext when extracting messages. + * `--keyword=Q_` to xgettext when extracting messages. * If you are using GNU gettext >= 0.15, you can also use - * to let xgettext split the context + * `--keyword=Q_:1g` to let xgettext split the context * string off into a msgctxt line in the po file. * * Returns: the translated message @@ -548,7 +548,7 @@ g_dngettext (const gchar *domain, * ]| * * If you are using the C_() macro, you need to make sure that you pass - * to xgettext when extracting messages. + * `--keyword=C_:1c,2` to xgettext when extracting messages. * Note that this only works with GNU gettext >= 0.15. * * Returns: the translated message @@ -611,7 +611,7 @@ g_dngettext (const gchar *domain, * ]| * * If you are using the NC_() macro, you need to make sure that you pass - * to xgettext when extracting messages. + * `--keyword=NC_:1c,2` to xgettext when extracting messages. * Note that this only works with GNU gettext >= 0.15. Intltool has support * for the NC_() macro since version 0.40.1. * diff --git a/glib/goption.c b/glib/goption.c index 17c35de..06c1912 100644 --- a/glib/goption.c +++ b/glib/goption.c @@ -52,9 +52,8 @@ * Another important feature of GOption is that it can automatically * generate nicely formatted help output. Unless it is explicitly turned * off with g_option_context_set_help_enabled(), GOption will recognize - * the , , - * and - * groupname options + * the `--help`, `-?`, `--help-all` and + * `--help-`groupname options * (where groupname is the name of a * #GOptionGroup) and write a text similar to the one shown in the * following example to stdout. @@ -326,7 +325,7 @@ G_DEFINE_QUARK (g-option-context-error-quark, g_option_error) /** * g_option_context_new: * @parameter_string: (allow-none): a string which is displayed in - * the first line of output, after the + * the first line of `--help` output, after the * usage summary * programname [OPTION...] * @@ -408,13 +407,12 @@ void g_option_context_free (GOptionContext *context) /** * g_option_context_set_help_enabled: * @context: a #GOptionContext - * @help_enabled: %TRUE to enable , %FALSE to disable it + * @help_enabled: %TRUE to enable `--help`, %FALSE to disable it * - * Enables or disables automatic generation of + * Enables or disables automatic generation of `--help` * output. By default, g_option_context_parse() recognizes - * , , - * , - * and groupname and creates + * `--help`, `-h`, `-?`, `--help-all` + * and `--help-`groupname and creates * suitable output to stdout. * * Since: 2.6 @@ -432,7 +430,7 @@ void g_option_context_set_help_enabled (GOptionContext *context, * g_option_context_get_help_enabled: * @context: a #GOptionContext * - * Returns whether automatic generation + * Returns whether automatic `--help` generation * is turned on for @context. See g_option_context_set_help_enabled(). * * Returns: %TRUE if automatic help generation is turned on. @@ -537,7 +535,7 @@ g_option_context_add_group (GOptionContext *context, * Sets a #GOptionGroup as main group of the @context. * This has the same effect as calling g_option_context_add_group(), * the only difference is that the options in the main group are - * treated differently when generating output. + * treated differently when generating `--help` output. * * Since: 2.6 **/ @@ -583,7 +581,7 @@ g_option_context_get_main_group (GOptionContext *context) * @context: a #GOptionContext * @entries: a %NULL-terminated array of #GOptionEntrys * @translation_domain: (allow-none): a translation domain to use for translating - * the output for the options in @entries + * the `--help` output for the options in @entries * with gettext(), or %NULL * * A convenience function which creates a main group if it doesn't @@ -755,9 +753,9 @@ context_has_h_entry (GOptionContext *context) * @group: (allow-none): the #GOptionGroup to create help for, or %NULL * * Returns a formatted, translated help text for the given context. - * To obtain the text produced by , call + * To obtain the text produced by `--help`, call * g_option_context_get_help (context, TRUE, NULL). - * To obtain the text produced by , call + * To obtain the text produced by `--help-all`, call * g_option_context_get_help (context, FALSE, NULL). * To obtain the help text for an option group, call * g_option_context_get_help (context, FALSE, group). @@ -1814,7 +1812,7 @@ platform_get_argv0 (void) * or some of the options after it start with '-'. In case * of an error, @argc and @argv are left unmodified. * - * If automatic support is enabled + * If automatic `--help` support is enabled * (see g_option_context_set_help_enabled()), and the * @argv array contains one of the recognized help options, * this function will produce help output to stdout and @@ -2157,11 +2155,11 @@ g_option_context_parse (GOptionContext *context, /** * g_option_group_new: * @name: the name for the option group, this is used to provide - * help for the options in this group with @name + * help for the options in this group with `--help-`@name * @description: a description for this group to be shown in - * . This string is translated using the translation + * `--help`. This string is translated using the translation * domain or translation function of the group - * @help_description: a description for the @name option. + * @help_description: a description for the `--help-`@name option. * This string is translated using the translation domain or translation function * of the group * @user_data: (allow-none): user data that will be passed to the pre- and post-parse hooks, @@ -2339,10 +2337,9 @@ g_option_group_set_error_hook (GOptionGroup *group, * @data: (allow-none): user data to pass to @func, or %NULL * @destroy_notify: (allow-none): a function which gets called to free @data, or %NULL * - * Sets the function which is used to translate user-visible - * strings, for output. Different - * groups can use different #GTranslateFuncs. If @func - * is %NULL, strings are not translated. + * Sets the function which is used to translate user-visible strings, + * for `--help` output. Different groups can use different + * #GTranslateFuncs. If @func is %NULL, strings are not translated. * * If you are using gettext(), you only need to set the translation * domain, see g_option_group_set_translation_domain(). @@ -2402,8 +2399,8 @@ g_option_group_set_translation_domain (GOptionGroup *group, * @destroy_notify: (allow-none): a function which gets called to free @data, or %NULL * * Sets the function which is used to translate the contexts - * user-visible strings, for output. - * If @func is %NULL, strings are not translated. + * user-visible strings, for `--help` output. If @func is %NULL, + * strings are not translated. * * Note that option groups have their own translation functions, * this function only affects the @parameter_string (see g_option_context_new()), @@ -2456,12 +2453,11 @@ g_option_context_set_translation_domain (GOptionContext *context, /** * g_option_context_set_summary: * @context: a #GOptionContext - * @summary: (allow-none): a string to be shown in output + * @summary: (allow-none): a string to be shown in `--help` output * before the list of options, or %NULL * - * Adds a string to be displayed in output - * before the list of options. This is typically a summary of the - * program functionality. + * Adds a string to be displayed in `--help` output before the list + * of options. This is typically a summary of the program functionality. * * Note that the summary is translated (see * g_option_context_set_translate_func() and @@ -2501,12 +2497,11 @@ g_option_context_get_summary (GOptionContext *context) /** * g_option_context_set_description: * @context: a #GOptionContext - * @description: (allow-none): a string to be shown in output + * @description: (allow-none): a string to be shown in `--help` output * after the list of options, or %NULL * - * Adds a string to be displayed in output - * after the list of options. This text often includes a bug reporting - * address. + * Adds a string to be displayed in `--help` output after the list + * of options. This text often includes a bug reporting address. * * Note that the summary is translated (see * g_option_context_set_translate_func()). diff --git a/glib/gtestutils.c b/glib/gtestutils.c index c9c0a4e..bf1ca21 100644 --- a/glib/gtestutils.c +++ b/glib/gtestutils.c @@ -1019,29 +1019,29 @@ parse_args (gint *argc_p, * * So far, the following arguments are understood: * - * - : List test cases available in a test executable. - * - : Provide a random seed to reproduce test + * - `-l`: List test cases available in a test executable. + * - `--seed=SEED`: Provide a random seed to reproduce test * runs using random numbers. - * - : Run tests verbosely. - * - , : Run tests quietly. - * - : Execute all tests matching the given path. + * - `--verbose`: Run tests verbosely. + * - `-q`, `--quiet`: Run tests quietly. + * - `-p PATH`: Execute all tests matching the given path. * This can also be used to force a test to run that would otherwise * be skipped (ie, a test whose name contains "/subprocess"). - * - : Execute tests according to these test modes: + * - `-m {perf|slow|thorough|quick|undefined|no-undefined}`: Execute tests according to these test modes: * - * : Performance tests, may take long and report results. + * `perf`: Performance tests, may take long and report results. * - * , : Slow and thorough tests, may take quite long and maximize coverage. + * `slow`, `thorough`: Slow and thorough tests, may take quite long and maximize coverage. * - * : Quick tests, should run really quickly and give good coverage. + * `quick`: Quick tests, should run really quickly and give good coverage. * - * : Tests for undefined behaviour, may provoke programming errors + * `undefined`: Tests for undefined behaviour, may provoke programming errors * under g_test_trap_subprocess() or g_test_expect_messages() to check * that appropriate assertions or warnings are given * - * : Avoid tests for undefined behaviour + * `no-undefined`: Avoid tests for undefined behaviour * - * - : Debug test logging output. + * - `--debug-log`: Debug test logging output. * * Since: 2.16 */ @@ -1778,8 +1778,7 @@ g_test_set_nonfatal_assertions (void) * * If @testpath includes the component "subprocess" anywhere in it, * the test will be skipped by default, and only run if explicitly - * required via the command-line option or - * g_test_trap_subprocess(). + * required via the `-p` command-line option or g_test_trap_subprocess(). * * Since: 2.16 */ @@ -1817,8 +1816,7 @@ g_test_add_func (const char *testpath, * * If @testpath includes the component "subprocess" anywhere in it, * the test will be skipped by default, and only run if explicitly - * required via the command-line option or - * g_test_trap_subprocess(). + * required via the `-p` command-line option or g_test_trap_subprocess(). * * Since: 2.16 */ -- 2.7.4