On Tue, 29 Dec 2020, Michael Balzer wrote:
There certainly are commands that don't need explanations, but let me pick an example that evolved into the opposite: "metrics list" originally didn't need an explanation. Then the parameter "[<metric>]" was added, which already isn't self-explaining, as a user will interpret it to be a full metric name, but it actually is a substring to match the metric names against. With "[-ps]" we finally crossed the border of "you need to read the source code to know what this does". It isn't even clear from the usage template that "p" and "s" are separate options.
Agreed. I was surprised to discover only a few days ago that the concept of option flags had arisen. A Unix usage message would explain each option flag. That mechanism doesn't fit cleanly with our parsing scheme because it means the arg number of the value parameter varies depending upon the presence of optional flags. Obviously this can be programmed, but it seems like another mechanism might be needed to use option flags cleanly.
No, we'll add that to the scripting API sections when the feature is available. This section should focus on the C++ API, and I meant the C++ side as well:
* different core modules may add commands to shared roots (e.g. "obdii" is shared now by the vehicle and obd2ecu modules) * unloadable modules (e.g. vehicles) need to deregister their commands on unload
Aha, more that I didn't know. I know that one can dynamically select what vehicle type is active, but do we have loadable modules in the sense of a separate binary that gets merged with the core binary?
I personally think we should avoid linking to the source code from the documentation. A developer won't need that link, more appropriate is including condensed example snippets. We did so on the scripting API sections, for example: https://docs.openvehicles.com/en/latest/userguide/scripting.html#pubsub
The "literalinclude" directive can be used to keep longer / full examples along with the source code but still render them nicely in the documentation.
Thinking more about this, you are right. For my examples it would be appropriate to just insert a code snippet. -- Steve