[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Bumping the help text API [was: svn commit: r1826328]

From: Julian Foad <julianfoad_at_apache.org>
Date: Thu, 15 Mar 2018 12:01:26 +0000

Daniel Shahaf wrote:
> julianfoad_at_apache.org wrote:
[...]
>> +/** The maximum number of paragraphs of help text a subcommand can have. */
>
> Missing "@since New in 1.11" annotation.
>
>> +#define SVN_OPT_MAX_PARAGRAPHS 50

Done.

>> @@ -77,6 +80,37 @@ typedef svn_error_t *(svn_opt_subcommand
>> /** One element of a subcommand dispatch table.
>> *
>> + * @since New in 1.11.
>> + */
>> +typedef struct svn_opt_subcommand_desc3_t
>> +{
> ...
>> +} svn_opt_subcommand_desc3_t;
>> +
>> +
>> +/** One element of a subcommand dispatch table.
>> + *
>> * @since New in 1.4.
>> */
>
> Mark as deprecated? (Also other symbols in this commit)
>
>> typedef struct svn_opt_subcommand_desc2_t

We should deprecate these, yes.

Done in r1826800.

It is a bit ugly. Most of the code is identical but the structure data
type is different. Lots of code duplication (introduced in r1826328).

Is there a better way?

If we were to move the new help text 'paragraphs' array to the end of
the struct leaving the old single string 'help' field in place (with
some definition of how they are combined or ignored), so that the
beginning of the new struct is identical to the whole of the old struct,
then we could cast one to the other and share some code.

I am not sure if such deduplication is worth the effort at this point.
The deprecated code can just sit there.

Also I am noticing some ugliness in the general svn_opt help API. For
example, many command-line programs print their version info by calling

   svn_opt_print_help4(NULL, "svnversion", TRUE, quiet, FALSE,
                       NULL, NULL, NULL, NULL, NULL, NULL, pool);

/**
  * Central dispatcher function for various kinds of help message.
  * Prints one of:
  * * subcommand-specific help (svn_opt_subcommand_help)
  * * generic help (svn_opt_print_generic_help)
  * * version info
  * * simple usage complaint: "Type '@a pgm_name help' for usage."
...*/

and so this had to be bumped to _help5() in 7 places. Dedicated API
functions would be better than using a 'central dispatcher' I think, for
the 'version info' case. Well, we already have one (and _help5 simply
forwards to it):

   svn_opt__print_version_info(...)

- Julian
Received on 2018-03-15 13:01:31 CET

This is an archived mail posted to the Subversion Dev mailing list.

This site is subject to the Apache Privacy Policy and the Apache Public Forum Archive Policy.