[PATCH] add documentation about backend naming for VMOD authors

[Dridi Boukelmoune]

> Let me try to summarize at an even higher level:

Good idea, I'll use it to summarize my position too.

> * All "struct director" (= VCL_BACKEND) have a "vcl_name" which can
>   be queried from VCL.  VMODs are responsible for doing something
>   sensible here.

Sounds good.

> * struct director without a struct backend do not appear in CLI/VSM
>   unless the VMOD implements all the stuff for this.

Sounds good, though I don't know how to implement it.

> * struct director with a struct backend, defined in VCL is always
>   in CLI/VSM, and the vcl_name is the name from the VCL namespace.

Sounds good, and for static backends defined in plain native vcl,
backend.display_name == vcl.loaded_name + "." + director.vcl_name

> * struct director with a struct backend, created by VMOD, may or
>   may not be in CLI/VSM, at the VMODs discretion.

They are currently always in the CLI/VSM, and this is controlled by
the VCL temperature changes. But I think a struct director with a
struct backend should always show up in the CLI/VSM.

> * If it is in CLI/VSM, the VRT() used to register it there may
>   modify the vcl_name to make sure it is globally unique.
>   (In practice: vcl-unique, because the namespace is $VCL.$BACKEND)

Since the CLI/VSM only show backends (not director) that would be the
backend's display_name. That is the part I'm not comfortable with, for
end-users.

> * If the VMOD ensures there are no duplicate vcl_names in the
>   first place, the vcl_name will not be touched.

The VMOD can enforce proper uniqueness, but can't prevent against name
collisions from other VMODs.