Tags and keywords
usageF function for ::usage String generation rather than the lower-level docF and docV functions (with direct '$doc$' Strings). For functions of any complexity and/or where argument and options sequences are shared between functions, use of an AOR Map (Arguments, Options, Rules) Association via the '$opt$aor' option for the usageF function is recommended (rather than "manually" creating help Rule Associations from 'rule$arg$' or 'rule$opt$' help Rules).
Conclusion on the Doc`, HelpF`, TestF`, HelpO`, and HelpM` packages
This concludes our quick tour of the Webel IT Australia packages for structured, code-oriented help for the Wolfram Language and Mathematica. We'll see many examples of their use throughout the rest of this slide trail. We've seen that:
- The Doc` packages offers lower-level packages at least some degree of DRY reuse of information for functions and their arguments and options carried by Webel '$opt$' and '$arg$' help holders, and structured
::usageString generation. - The HelpF` package offers a help registry for functions and their options and arguments and rich convenient interactive views and queries, with a high level of DRY reuse through code-oriented help registration, and
::usageString generation completely consistent with the help registry views. - The TestF` package offers test automation over package functions.
- A Webel AOR Map (Arguments, Options, Rules) Association can be used for a single function or for convenient grouping of shared arguments and/or options through highly automated use of Webel '$opt$' and '$arg$' help holders, and can be used to share options groups between functions, and to consistently manage their Wolfram Language
Options[]. - The HelpO` package offers a help registry for class methods and their arguments and options and rich interactive help views and queries, with a high level of DRY reuse through code-oriented help registration. It can be used both for MTools classes and methods and for Webel ADT stateless pseudo classes and their TagSetDelayed "methods".
We haven't looked into the HelpM` package in much detail yet, but we've seen quickly how it offers encapsulation of help through classes for MTools projects. It extends the HelpO` package with help aspects specific to the user-contributed MTools package. We'll see it in action later when we learn more about the All` package and the Webel MAll universal class that all Webel applications classes that use MTools extend.
How to handle MClass and MMethod for ::usage docs is still a work-in-progress as regards MTools methods, as it apparently can't be combined with the MTools method syntax. A ::usage can be created for a TagSetDelayed "method" of a Webel ADT pseudo class but it apparently can't be made specific to class context.
With additional metadata fields the MPackage and supporting MFunction, MArg, and MOpt classes could in principle by used to completely generate Documentation Center compliant documentation, although that capability is currently a low priority for the Webel projects.
The primary documentation of package functions and class methods on Webel projects using Mathematica is the HelpF` and HelpO` registries.