elvish icon indicating copy to clipboard operation
elvish copied to clipboard

Variables in the `builtin:` namespace do not include a usage while those in other namespaces do

Open krader1961 opened this issue 2 years ago • 1 comments

Compare https://elv.sh/ref/builtin.html#after-chdir to https://elv.sh/ref/math.html#math:e. I noticed this inconsistency when implementing a help command. Personally, I don't think there is any value in a "usage" block for variables and all of the non-builtin modules should omit such blocks since the redundant usage blocks simply repeat that the variable is dereferenced by a dollar-sign prefix. Thus, they don't add any information. Alternatively, the builtin: variable definitions should include a "usage" block for consistency with the variables in the non-builtin: modules.

krader1961 avatar Jul 14 '22 02:07 krader1961

Note that other namespaces do not include a redundant "usage" block for variables; e.g., https://elv.sh/ref/platform.html and https://elv.sh/ref/unix.html. In fact, it looks like math: is the outlier. So I'm going to create a pull-request that brings it into conformance with all the other namespaces.

krader1961 avatar Jul 14 '22 02:07 krader1961