| Puppet Strings currently supports, via YARD, the ability to add extended documentation to a parameter which expects a hash to document the various keys expected using the @option tag. This is quite useful. Parameters that are of the Puppet Enum type would also benefit from this type of extended option documentation. However, the @option tag is not suitable as it expects a data type to be provided, which makes no sense in the context of an Enum. You can put an arbitrary value as the datatype, but it results in a poor user experience for both the person documenting and the person reading the documentation. Instead I propose adding a new tag, @enum, that behaves similarly to @option but does not expect a data type to be passed and renders the results accordingly (but otherwise similarly to @option). |
