[master] 6aeb824f1 doc: Document how vmodtool.py generates C symbol names

[Nils Goroll]

commit 6aeb824f115a5c9693484cec4021b13964a664d0
Author: Nils Goroll <nils.goroll at uplex.de>
Date:   Thu Apr 17 12:11:33 2025 +0200

    doc: Document how vmodtool.py generates C symbol names
    
    in preparation of the changes from #4240
    
    "write the documentation first" did not always apply in the past...

diff --git a/doc/sphinx/reference/vmod.rst b/doc/sphinx/reference/vmod.rst
index cf28deac0..781929383 100644
--- a/doc/sphinx/reference/vmod.rst
+++ b/doc/sphinx/reference/vmod.rst
@@ -121,7 +121,7 @@ For the std VMOD, the compiled vcc_if.h file looks like this::
 	vmod_event_f event_function;
 
 Those are your C prototypes.  Notice the ``vmod_`` prefix on the
-function names.
+function names, more on that in :ref:`ref-vmod-symbols`.
 
 Named arguments and default values
 ----------------------------------
@@ -512,6 +512,51 @@ VOID
 	Can only be used for return-value, which makes the function a VCL
 	procedure.
 
+.. _ref-vmod-symbols:
+
+C symbols
+=========
+
+Through generation of ``vcc_if.h``, ``vmodtool.py`` pre-defines the names of
+most symbols on the C side of the vmod interface, namely:
+
+* function names as *<prefix>_<function>*
+
+* event handler names as *<prefix>_<handler>*
+
+* method names as *<prefix>_<class>_<method>*, with two special methods named
+
+  * ``_init`` for the constructor and
+  * ``_fini`` for the destructor
+
+* class struct names as *<prefix>_<vmod>_<class>*
+
+* argument struct names for support of optional arguments as
+  *arg_<prefix>_<vmod>_<function>* for functions and
+  *arg_<prefix>_<vmod>_<class>_<method>* for methods, with member names
+
+  * *valid_<argument>* for the flag of optional arguments being present and
+  * *<argument>* for the argument name
+
+* enum values as *enum_<prefix>_<vmod>_<value>*
+
+For the above, the *<xxx>* placeholders are defined as:
+
+*<prefix>*
+        The ``$Prefix`` stanza value, if defined in the ``.vcc`` file, or
+        ``vmod`` by default.
+
+*<vmod>*
+        The vmod name fro the ``$Module`` stanza of the ``.vcc`` file.
+
+*<argument>*
+        The function or method argument name
+
+The other placeholders should be self-explanatory as the name of the respective
+function, class, method or handler name.
+
+In summary, only some symbol names (those with *<prefix>*) can be influenced by
+the vmod author.
 
 .. _ref-vmod-private-pointers: