Doc` package ::usage help generation using the docV and docF functions (2)

Recall that the Webel Doc` package supports lower level packages that do not import the more powerful HelpF` and HelpO` help registry packages or that do not use the Entity-based Var` variable registry package. Doc` is therefore "String based ", i.e., its concept of a variable or argument is its String name, not its Symbol.

However, Doc` can leverage the Webel '$arg$' and '$opt$' conventions because it is itself the very package that defines those conventions.

The frequently used pressure p in this example a name "p" stored as a '$arg$psy$p' String help holder, where the 'psy' grouping qualifier stands for the Webel Psy` Psychrometrics (humid air physics) package.

Note, however, that this simple example does not yet use a 'rule$arg'; we saw earlier that a 'rule$arg' could in fact also be used to generate the '$doc$arg$' String:

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

Of, if a package may depend on MTools:

HelpM`: Use Webel MOpt and MArg objects to create ‘$doc$’ Strings for ::usage help

HelpM`: Use MFunction and MMethod with MArg & MOpt for ::usage (and consistent with the HelpF` and HelpO` registries)

We'll also see later that even without MTools and the Webel HelpM` classes those packages that also import HelpF` can still benefit from a higher level of automation and help integration using the AOR Map (Arguments, Options, Rules) Association. For reference (but it's best for now to just stay with the trail):

Webel: Mathematica: Packages that import the Webel HelpF` package (but not MTools and the Webel HelpM` package) should use the 'usageF' function for ::usage String generation (rather than the 'docF' and 'docV' functions) and an AOR Map.

Up next

Why the Webel HelpF` & HelpO` registries?

Notes

[CONVENTION, NAMING, POLICY]{SUGGESTED} Webel: Mathematica: CONVENTION: A '$doc$' prefix indicates a formatted documentation String helper. A '$doc$arg$' is for an argument, a '$doc$opt$' is for an option. A '$doc$ String may be used to create ::usage documentation via docF.

[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.

[CONVENTION, NAMING, POLICY]{SUGGESTED} Webel: Mathematica: CONVENTION: A '$sig$f$' prefix indicates a String signature helper for a function (or for a "method" of an MTools class or a Webel Abstract Data Type (ADT) pseudo class).

[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: 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 ...

[CONVENTION, POLICY, TIP]{STRONG} Webel: Mathematica: Packages that import the Webel HelpF` package (but not MTools and the Webel HelpM` package) should use the 'usageF' function for ::usage String generation (rather than the 'docF' and 'docV' functions) and an AOR Map.

Snippets (quotes/extracts)

Visit also