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

The String signature for a function for use as the 1st argument to docF can be manually provided or - using the Webel ET` package as we'll see later - generated from the ExpressionTree for a function (or class "method"). There is therefore seldom reason to store a signature String in a '$sig$f$' helper, and as we'll see later, the HelpF` and HelpO` help registry packages can elicit the "signature(s)" anyway.

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

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

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