!usermacros: Omit Macros Whose Name Starts with Underscore
tajmone opened this issue · comments
When building a set of macros, sometimes I also add some "internal" macros — ie: macros not intended to be used by endusers, but just by the macros, for secondary tasks. Usually I give these internal macros names starting with an underscore, to distinguish them from the actual enduser macros.
I was thinking that it would be nice if !usermacros and !userhelp would ignore macros starting with an "_". This would help keeping a clean auto-generated documentation, without showing certain macros. My guess is that usually no one would use such a naming convention unless it was some sort of internal-usage stuff, therefore it shouldn't interfere with most existing macros collections.
!userhelp lists only macros that have been documented. Should !usermacros also list only documented macros?
Unexported macros could then be commented but not documented.
Should
!usermacrosalso list only documented macros?
No, I think that most users would expect !usermacros to list all user defined macros. Some macros might have a self-explaining name and need not be documented, or just be variant of other macros (eg: !turnWhite, !turnBlack, !turnRed, etc.) where only the first one appearing in the list needs to be documented, the others being obvious variations — since documentation is only viewable as a full list via !usermacros, variants need not be document; if individual macros' documentation was accessible via a !help( MACRONAME ) parameter then it would be different.
But the idea is interesting, and maybe having also a !documentedusermacros could be useful in the context of auto-generated documentation.
The idea of underscored macros being unlisted by any of the above built-in macros is strictly related to their being internal-use-only macros. And if in the future the !help( MACRONAME ) syntax were to be implemented, they could be documented too, without showing up in !usermacros.
But I'm suggesting this based on my way of doing things, and assuming that having an underscore as first name character would seem a special use-case to most people, and that some internal macros need not be exposed to user documentation.
pp 2.2.1 does not list user macros starting with _.