Generate shared option groups using ‘$opt$’ helpers: wl$optsFromOpts, docsFromOpts, rulesFromOpts, and odrMap triplet

Gallery
Tutorial
[TECHNICAL SLIDE TRAIL] The Webel libraries for Wolfram Mathematica: With SysMLv1 models.
Section
SECTION: The Webel Doc` package and the HelpF, HelpO`& HelpM` help registry packages
Mathematica keywords
::usage
Webel Mathematica keywords
W`Base`
HelpF`
addFunction
'$info$f$'
'$opt$'
'rule$opt$'
'$sig$f$'
odrMap
docsFromOpts
rulesFromOpts
wl$optsFromOpts
Keywords
Click on the image to view it full size

The Webel ODR Map (Options, Docs, Rules) Association "triplet" Association strategy provides for packages that import the Doc` package a higher level of Don't Repeat Yourself (DRY) reuse than available to just the Doc` package itself. Each triplet aspect can be used in many other ways and all generated from information in the same underlying '$opt$' help holders.

But recall that we are progressively "boot-strapping" the system. The Doc` package can't fully leverage the ODR triplets itself, and HelpF` can only partially leverage its own functions, because ::usage documentation Strings can't use SetDelayed.

Please note that the ODR Map (Options, Docs, Rules) Association is for lower level packages that only import Doc` (and especially HelpF`). Higher level packages that import the HelpF` or HelpO` packages should instead use an AOR Map (Arguments, Options, Rules) Association that integrates fully with the usageF, addFunction, and addMethod functions.

Downstream application packages that import both Doc` and HelpF` can get a high level of Don't Repeat Yourself (DRY) reuse (and even without using the Webel MTools helper classes).

In later slides we'll see how - if we indeed use MTools and the Webel MFunction, MMethod, and MClass classes from the HelpM` package - we can get complete integration between the Webel '$arg$' and '$opt$' help holders, structured :usage generation, Options group extraction, and registration of rich information with the Webel HelpF` and HelpO` registries.

Up next
HelpF`: OptionsPattern groups as SysML shared between functions
Notes
[CONVENTION, NAMING, PATTERN, POLICY]{STRICT} Webel: Mathematica: CONVENTION: A function's description (but not its signature, arguments, or options) may be captured as an '$info$f$' Stringhelp holder for use by the Doc` package for ::usage generation and the HelpF`& HelpO` help registry packages.
[NAMING, PATTERN, POLICY]{STRICT} Webel: Mathematica: CONVENTION: Option help holders use a String variable with the prefix '$opt$', a related '$info$opt$' String, a 'def$opt$' default value expression, and optional '$warn$opt$', '$tip$opt$', '$lab$opt$', and 'type$opt$' indicator ...
[NAMING, PATTERN, POLICY]{STRICT} Webel: Mathematica: A help Rule 'rule$opt$' for an '$opt$' (option) accepts keys: '$k$help' (required), '$k$def' (required), and optional '$k$warn', '$k$tip', '$k$lab' (a label), '$k$type' (indicator only), '$k$mult' (SysML multiplicity), and '$k$pat'.
Snippets (quotes/extracts)
Visit also
Visit also (backlinks)
Related slides (includes other tutorials)
Why the Webel HelpF` & HelpO` registries?
HelpF`example: helpFunction[$pac$HelpF, addFunction]
DRY not WET! "Don't Repeat Yourself!"
HelpF`example: addFunction (1)
HelpF`example: addFunction (2)
Generate $doc$arg$ and $doc$opt$ Strings from Webel help Rules for use in ::usage
Doc` package ::usage help generation using the docV and docF functions (1)
Doc` package ::usage help generation using the docV and docF functions (2)
HelpM`: Use MFunction and MMethod with MArg & MOpt for ::usage (and consistent with the HelpF` and HelpO` registries)
Related slides (backlinks, includes other tutorials)
The AOR Map (Attributes, Options, Rules) Association: Example: aor$f$helpClass