The Webel '$opt$', 'rule$opt$', '$arg$', 'rule$arg$' and supporting '$k$' conventions for "help holders"

For reference, some related Webel convention policy notes (explored in more detail also in later slides). For now it's recommended that you don't visit these links yet but instead just view the next trail slide:

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

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$'..

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

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'

A help Rule (typically generated from other help holders) uses '$k$' keys for registration of help on an option or argument with the HelpF` and HelpO` help registries:

Webel: Mathematica: CONVENTION: Where keys of Associations are Strings they are encapsulated as variables prefixed with '$k$' (promotes DRY and has many advantages, such as IDE prompting). Direct use of "Strings" as keys is WET and strongly discouraged!

Use of a SysML-style '$mult$' multiplicity indicator is optional and only used for additional documentation. If not provided for an option it will be assumed to be "[0..1]" for a generated help Rule for an option.

A '$pat$' Pattern helper may be assigned to an (optional) '$type$' type indicator, which serves only as additional documentation. Use of a 'pat$' encapsulated Pattern is completely optional; it is very rarely used for an option but can sometimes be useful for arguments (but is not very IDE-friendly):

Webel: Mathematica: CONVENTION: "pattern helpers" (which are not themselves Patterns) use the prefix '$pat$. Encapsulated Patterns use a 'pat$' prefix, and may use a '$pat$' pattern helper (such as an Alternatives).

One main (but not the only) reason for the Webel '$opt$' and '$arg$' help holders approach (which relies at least for lower-level packages on "manually coded" naming conventions) is that it offers lower-level packages at least some DRY resuse help support without relying on the full "downstream" help packages:

The very low-level packages like Devel` can only use the '$opt$' and '$arg$' help holders and associated help Rules completely "manually" by convention.
Packages that import the Doc` package have more support for the help holders and help Rule generation, and some ::usage String generation, as well as consistency checks, and some basic package/function help query views.
Packages that import the HelpF` and HelpO` help registry packages have even more support and a higher level of generative automation, and rich help views and help queries for Notebooks. Any help holders from lower-level packages can also be used, and with full integration of help on attributes, options, and Wolfram Language Options[] Rules via a AOR Map, 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.

And even if the Wolfram Language did have built-in support for classes and object-orientation - instead of using MTools, or Webel Abstract Data Type (ADT) stateless pseudo classes - there would still be compelling reasons to have the '$opt$' and '$arg$' help holders, such as IDE-friendly DRY default management for arguments. And the help holders can leverage all of the power of the Wolfram Language directly, such as using := SetDelayed. (Note however that use of forward references via := SetDelayed to functions of packages that have not been imported is discouraged.)