Generate $doc$arg$ and $doc$opt$ Strings from Webel help Rules for use in ::usage

Gallery
Tutorial
[TECHNICAL SLIDE TRAIL] The Webel libraries for Wolfram Mathematica: With SysMLv1 models.
Section
SECTION: The Webel '$opt$' and '$arg$' help holder conventions for options and arguments in the Wolfram Language
Mathematica keywords
Options
::usage
Webel Mathematica keywords
help holder
'$arg$'
'rule$arg$'
'$opt$'
'rule$opt$'
help Rule
docFromArgRule
docFromOptRule
'$doc$arg$'
'$doc$opt$'
'$doc$'
Keywords
Click on the image to view it full size

Please note that generation of '$doc$' String snippets using docV for combination via docF to create a ::usage String from 'rule$arg$' and 'rule$doc$' help Rules for Webel '$opt$' and '$arg$' help holders is only for very low-level utility packages that don't import the full "downstream" help packages.

Packages that import the HelpF` and HelpO` help registry packages have a much a higher level of generative automation, and full integration of help on attributes, options, and Wolfram Language Options[] Rules via an AOR Map (Arguments, Options, Rules) Association, which can be used both for ::usage generation via the usageF function and for registration via addFunction and addMethod.

In later slides we'll see how Webel extensions in the HelpM` package of the user-contributed MTools classes package such as the MArg, MOpt, MFunction, and MMethod classes can be used together to encapsulate the help holders for the Webel help holder conventions, and how they work with the HelpF` and HelpO` help registries and with highly structured ::usage generation, all completely integrated.

Up next
When to use explicit $arg$ help holders (in lower level utility packages)
Notes
[NAMING, PATTERN, POLICY]{STRICT} Webel: Mathematica: A help Rule 'rule$arg' for an '$arg$' (argument) accepts keys: '$k$help' (required), '$k$def' (required if $k$req = True not given), '$k$req' (True if $k$def not given), '$k$warn', '$k$tip', '$k$lab', '$k$type', '$k$mult' and '$k$pat'
[NAMING, PATTERN, POLICY]{STRICT} Webel: Mathematica: CONVENTION: Argument help holders use a String variable with the prefix '$arg$', a related '$info$arg$' String, a 'def$arg$' default value expression and/or 'req$arg$', and optional '$warn$arg$', '$tip$arg$, '$lab$arg$', 'type$arg$'..
[NAMING, PATTERN, POLICY]{STRICT} Webel: Mathematica: CONVENTION: An '$opt$' (option) or '$arg$ (argument) help holder may be have an associated (typically short) '$lab$opt$' or '$lab$arg$' label help holder for use in GUIs and views.
[POLICY]{STRONG} About the Single Source of Truth (SSOT) and Don't Repeat Yourself (DRY) principles
[NAMING, OPTION, PATTERN, TIP]{OPTION} Mathematica: Webel: You CAN/MAY use $ in variable names and function names - just not as the first character before a Capital - and it's extremely useful. You won't get sent to Azkaban prison if do you use a $ character!
[CONVENTION, NAMING]{STRICT} Webel: Mathematica: CONVENTION: A prefix '$doc' indicates a documentation String for each primary variable/quantity (argument or output)
Snippets (quotes/extracts)
Related slides (includes other tutorials)
The Webel '$opt$', 'rule$opt$', '$arg$', 'rule$arg$' and supporting '$k$' conventions for "help holders"
Webel ‘$arg$’, ‘def$arg$’, and ‘rule$arg$’ convention
Webel '$arg$' and '$opt$' support via the Doc` package
Make a Webel help Rule for a required ‘$arg$’ argument + conventions
Related slides (backlinks, includes other tutorials)
HelpM`: Use Webel MOpt and MArg objects to create ‘$doc$’ Strings for ::usage help
Doc` package ::usage help generation using the docV and docF functions (2)
Generate shared option groups using ‘$opt$’ helpers: wl$optsFromOpts, docsFromOpts, rulesFromOpts, and odrMap triplet
HelpF`: OptionsPattern groups as SysML shared between functions
HelpF`: OptionsPattern groups as SysML shared between functions
Webel ODR (Options, Docs, Rules) as SysML
Webel ODR (Options, Docs, Rules) as SysML
Visit also
The Webel SysML4Mathematica recipe for modelling Wolfram Language code in Systems Modeling Language (SysML) for Model-Based Systems Engineering
Visit also (backlinks)
Webel: Mathematica: CONVENTION: A prefix '$doc' indicates a documentation String for each primary variable/quantity (argument or output)