[Ovmsdev] Addition to OVMS Developer Guide

[Stephen Casner]

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