docs: clean up the dynamic modules logs docs (#42768)

## Description

This PR addresses minor styling nits in the Dynamic Modules
(Network/HTTP) docs.

---

**Commit Message:** docs: clean up the dynamic modules logs docs
**Additional Description:** Addresses minor styling nits in the Dynamic
Modules (Network/HTTP) docs.
**Risk Level:** N/A
**Testing:** CI
**Docs Changes:** N/A
**Release Notes:** N/A

---------

Signed-off-by: Rohit Agrawal <[email protected]>
Co-authored-by: phlax <[email protected]>

Mirrored from https://github.com/envoyproxy/envoy @ 98b0f479f50000c0daca5abcb006b1074323931c

Author: update-envoy[bot]

envoy/extensions/dynamic_modules/v3/dynamic_modules.proto

@@ -11,46 +11,59 @@ option java_multiple_files = true;
 option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/dynamic_modules/v3;dynamic_modulesv3";
 option (udpa.annotations.file_status).package_version_status = ACTIVE;
 
-// [#protodoc-title: Dynamic Modules common configuration]
+// [#protodoc-title: Dynamic Modules Common Configuration]
 
-// Configuration of a dynamic module. A dynamic module is a shared object file that can be loaded via dlopen
-// by various Envoy extension points. Currently, only HTTP filter (envoy.filters.http.dynamic_modules) is supported.
+// Configuration of a dynamic module. A dynamic module is a shared object file that can be loaded via
+// ``dlopen`` by various Envoy extension points.
 //
-// How a module is loaded is determined by the extension point that uses it. For example, the HTTP filter
-// loads the module with dlopen when Envoy receives a configuration that references the module at load time.
-// If loading the module fails, the configuration will be rejected.
+// How a module is loaded is determined by the extension point that uses it. For example, the HTTP
+// filter loads the module when Envoy receives a configuration that references the module. If loading
+// the module fails, the configuration will be rejected.
 //
-// Whether or not the shared object is the same is determined by the file path as well as the file's inode depending
-// on the platform. Notably, if the file path and the content of the file are the same, the shared object will be reused.
+// A module is uniquely identified by its file path and the file's inode, depending on the platform.
+// Notably, if the file path and the content of the file are the same, the shared object will be
+// reused.
 //
-// A module must be compatible with the ABI specified in :repo:`abi.h <source/extensions/dynamic_modules/abi.h>`.
-// Currently, compatibility is only guaranteed by an exact version match between the Envoy
-// codebase and the dynamic module SDKs. In the future, after the ABI is stabilized, we will revisit
-// this restriction and hopefully provide a wider compatibility guarantee. Until then, Envoy
-// checks the hash of the ABI header files to ensure that the dynamic modules are built against the
-// same version of the ABI.
+// A module must be compatible with the ABI specified in :repo:`abi.h
+// <source/extensions/dynamic_modules/abi.h>`. Currently, compatibility is only guaranteed by an
+// exact version match between the Envoy codebase and the dynamic module SDKs. In the future, after
+// the ABI is stabilized, this restriction will be revisited. Until then, Envoy checks the hash of
+// the ABI header files to ensure that the dynamic modules are built against the same version of the
+// ABI.
 message DynamicModuleConfig {
-  // The name of the dynamic module. The client is expected to have some configuration indicating where to search for the module.
-  // In Envoy, the search path can only be configured via the environment variable ``ENVOY_DYNAMIC_MODULES_SEARCH_PATH``.
-  // The actual search path is ``${ENVOY_DYNAMIC_MODULES_SEARCH_PATH}/lib${name}.so``. TODO: make the search path configurable via
-  // command line options.
+  // The name of the dynamic module.
+  //
+  // The client is expected to have some configuration indicating where to search for the module. In
+  // Envoy, the search path can only be configured via the environment variable
+  // ``ENVOY_DYNAMIC_MODULES_SEARCH_PATH``. The actual search path is
+  // ``${ENVOY_DYNAMIC_MODULES_SEARCH_PATH}/lib${name}.so``.
+  //
+  // .. note::
+  //   There is some remaining work to make the search path configurable via command line options.
   string name = 1 [(validate.rules).string = {min_len: 1}];
 
-  // Set true to prevent the module from being unloaded with dlclose.
-  // This is useful for modules that have global state that should not be unloaded.
-  // A module is closed when no more references to it exist in the process. For example,
-  // no HTTP filters are using the module (e.g. after configuration update).
+  // If true, prevents the module from being unloaded with ``dlclose``.
+  //
+  // This is useful for modules that have global state that should not be unloaded. A module is
+  // closed when no more references to it exist in the process. For example, no HTTP filters are
+  // using the module (e.g. after configuration update).
+  //
+  // Defaults to ``false``.
   bool do_not_close = 3;
 
-  // The dynamic module is loaded with ``RTLD_LOCAL`` flag to avoid symbol conflicts when multiple
-  // modules are loaded by default. Set this to true to load the module with ``RTLD_GLOBAL`` flag.
-  // This is useful for modules that need to share symbols with other dynamic libraries. For
-  // example, a module X may load another shared library Y that depends on some symbols defined
-  // in module X. In this case, module X must be loaded with ``RTLD_GLOBAL`` flag so that the
-  // symbols defined in module X are visible to library Y.
+  // If true, the dynamic module is loaded with the ``RTLD_GLOBAL`` flag.
+  //
+  // The dynamic module is loaded with the ``RTLD_LOCAL`` flag by default to avoid symbol conflicts
+  // when multiple modules are loaded. Set this to ``true`` to load the module with the
+  // ``RTLD_GLOBAL`` flag. This is useful for modules that need to share symbols with other dynamic
+  // libraries. For example, a module X may load another shared library Y that depends on some
+  // symbols defined in module X. In this case, module X must be loaded with the ``RTLD_GLOBAL``
+  // flag so that the symbols defined in module X are visible to library Y.
   //
   // .. warning::
-  //   Use this option with caution as it may lead to symbol conflicts and undefined behavior
-  //   if multiple modules define the same symbols and are loaded globally.
+  //   Use this option with caution as it may lead to symbol conflicts and undefined behavior if
+  //   multiple modules define the same symbols and are loaded globally.
+  //
+  // Defaults to ``false``.
   bool load_globally = 4;
 }

envoy/extensions/filters/http/dynamic_modules/v3/dynamic_modules.proto

@@ -14,40 +14,47 @@ option java_multiple_files = true;
 option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/http/dynamic_modules/v3;dynamic_modulesv3";
 option (udpa.annotations.file_status).package_version_status = ACTIVE;
 
-// [#protodoc-title: HTTP filter for dynamic modules]
+// [#protodoc-title: Dynamic Modules HTTP Filter]
 // [#extension: envoy.filters.http.dynamic_modules]
 
-// Configuration of the HTTP filter for dynamic modules. This filter allows loading shared object files
-// that can be loaded via dlopen by the HTTP filter.
+// Configuration for the Dynamic Modules HTTP filter. This filter allows loading shared object files
+// that can be loaded via ``dlopen`` to extend the HTTP filter chain.
 //
-// A module can be loaded by multiple HTTP filters, hence the program can be structured in a way that
-// the module is loaded only once and shared across multiple filters providing multiple functionalities.
+// A module can be loaded by multiple HTTP filters; the module is loaded only once and shared across
+// multiple filters.
 //
-// A dynamic module HTTP filter can opt into being a terminal filter with no upstream by setting ``terminal_filter`` to
-// true in the configuration. A terminal dynamic module can use ``send_`` ABI methods to send response headers,
-// body and trailers to the downstream.
+// A dynamic module HTTP filter can opt into being a terminal filter with no upstream by setting
+// :ref:`terminal_filter
+// <envoy_v3_api_field_extensions.filters.http.dynamic_modules.v3.DynamicModuleFilter.terminal_filter>`
+// to ``true``. A terminal dynamic module can use ``send_`` ABI methods to send response headers,
+// body, and trailers to the downstream.
 message DynamicModuleFilter {
   // Specifies the shared-object level configuration.
   envoy.extensions.dynamic_modules.v3.DynamicModuleConfig dynamic_module_config = 1;
 
-  // The name for this filter configuration. This can be used to distinguish between different filter implementations
-  // inside a dynamic module. For example, a module can have completely different filter implementations.
-  // When Envoy receives this configuration, it passes the filter_name to the dynamic module's HTTP filter config init function
-  // together with the filter_config.
-  // That way a module can decide which in-module filter implementation to use based on the name at load time.
+  // The name for this filter configuration.
+  //
+  // This can be used to distinguish between different filter implementations inside a dynamic
+  // module. For example, a module can have completely different filter implementations. When Envoy
+  // receives this configuration, it passes the ``filter_name`` to the dynamic module's HTTP filter
+  // config init function together with the ``filter_config``. That way a module can decide which
+  // in-module filter implementation to use based on the name at load time.
   string filter_name = 2;
 
-  // The configuration for the filter chosen by filter_name. This is passed to the module's HTTP filter initialization function.
-  // Together with the filter_name, the module can decide which in-module filter implementation to use and
+  // The configuration for the filter chosen by ``filter_name``.
+  //
+  // This is passed to the module's HTTP filter initialization function. Together with the
+  // ``filter_name``, the module can decide which in-module filter implementation to use and
   // fine-tune the behavior of the filter.
   //
-  // For example, if a module has two filter implementations, one for logging and one for header manipulation,
-  // filter_name is used to choose either logging or header manipulation. The filter_config can be used to
-  // configure the logging level or the header manipulation behavior.
+  // For example, if a module has two filter implementations, one for logging and one for header
+  // manipulation, ``filter_name`` is used to choose either logging or header manipulation. The
+  // ``filter_config`` can be used to configure the logging level or the header manipulation
+  // behavior.
   //
-  // ``google.protobuf.Struct`` is serialized as JSON before
-  // passing it to the plugin. ``google.protobuf.BytesValue`` and
-  // ``google.protobuf.StringValue`` are passed directly without the wrapper.
+  // ``google.protobuf.Struct`` is serialized as JSON before passing it to the plugin.
+  // ``google.protobuf.BytesValue`` and ``google.protobuf.StringValue`` are passed directly without
+  // the wrapper.
   //
   // .. code-block:: yaml
   //
@@ -63,35 +70,42 @@ message DynamicModuleFilter {
   //
   google.protobuf.Any filter_config = 3;
 
-  // Set true if the dynamic module is a terminal filter to use without an upstream.
+  // If ``true``, the dynamic module is a terminal filter to use without an upstream.
+  //
   // The dynamic module is responsible for creating and sending the response to downstream.
+  //
+  // Defaults to ``false``.
   bool terminal_filter = 4;
 }
 
-// Configuration of the HTTP per-route filter for dynamic modules. This filter allows loading shared object files
-// that can be loaded via dlopen by the HTTP filter.
+// Configuration of the HTTP per-route filter for dynamic modules.
 message DynamicModuleFilterPerRoute {
   // Specifies the shared-object level configuration.
   envoy.extensions.dynamic_modules.v3.DynamicModuleConfig dynamic_module_config = 1;
 
-  // The name for this filter configuration. This can be used to distinguish between different filter implementations
-  // inside a dynamic module. For example, a module can have completely different filter implementations.
-  // When Envoy receives this configuration, it passes the filter_name to the dynamic module's HTTP per-route filter config init function
-  // together with the filter_config.
-  // That way a module can decide which in-module filter implementation to use based on the name at load time.
+  // The name for this filter configuration.
+  //
+  // This can be used to distinguish between different filter implementations inside a dynamic
+  // module. For example, a module can have completely different filter implementations. When Envoy
+  // receives this configuration, it passes the ``per_route_config_name`` to the dynamic module's
+  // HTTP per-route filter config init function together with the ``filter_config``. That way a
+  // module can decide which in-module filter implementation to use based on the name at load time.
   string per_route_config_name = 2;
 
-  // The configuration for the filter chosen by filter_name. This is passed to the module's HTTP per-route filter initialization function.
-  // Together with the filter_name, the module can decide which in-module filter implementation to use and
-  // fine-tune the behavior of the filter on a specific route.
+  // The configuration for the filter chosen by ``per_route_config_name``.
+  //
+  // This is passed to the module's HTTP per-route filter initialization function. Together with
+  // the ``per_route_config_name``, the module can decide which in-module filter implementation to
+  // use and fine-tune the behavior of the filter on a specific route.
   //
-  // For example, if a module has two filter implementations, one for logging and one for header manipulation,
-  // filter_name is used to choose either logging or header manipulation. The filter_config can be used to
-  // configure the logging level or the header manipulation behavior.
+  // For example, if a module has two filter implementations, one for logging and one for header
+  // manipulation, ``per_route_config_name`` is used to choose either logging or header
+  // manipulation. The ``filter_config`` can be used to configure the logging level or the header
+  // manipulation behavior.
   //
-  // ``google.protobuf.Struct`` is serialized as JSON before
-  // passing it to the plugin. ``google.protobuf.BytesValue`` and
-  // ``google.protobuf.StringValue`` are passed directly without the wrapper.
+  // ``google.protobuf.Struct`` is serialized as JSON before passing it to the plugin.
+  // ``google.protobuf.BytesValue`` and ``google.protobuf.StringValue`` are passed directly without
+  // the wrapper.
   //
   // .. code-block:: yaml
   //

envoy/extensions/filters/network/dynamic_modules/v3/dynamic_modules.proto

@@ -14,42 +14,43 @@ option java_multiple_files = true;
 option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/network/dynamic_modules/v3;dynamic_modulesv3";
 option (udpa.annotations.file_status).package_version_status = ACTIVE;
 
-// [#protodoc-title: Network filter for dynamic modules]
+// [#protodoc-title: Dynamic Modules Network Filter]
 // [#extension: envoy.filters.network.dynamic_modules]
 
-// Configuration of the network filter for dynamic modules. This filter allows loading shared object
-// files that can be loaded via dlopen by the network filter.
+// Configuration for the Dynamic Modules network filter. This filter allows loading shared object
+// files that can be loaded via ``dlopen`` to extend the network filter chain.
 //
-// A module can be loaded by multiple network filters, hence the program can be structured in a way
-// that the module is loaded only once and shared across multiple filters providing multiple
-// functionalities.
+// A module can be loaded by multiple network filters; the module is loaded only once and shared
+// across multiple filters.
 //
-// Unlike HTTP filters which operate on structured headers, body, and trailers, network filters
-// work with raw TCP byte streams. The filter can:
+// Unlike HTTP filters which operate on structured headers, body, and trailers, network filters work
+// with raw TCP byte streams. The filter can:
 //
 // * Inspect, modify, or inject data into the downstream connection.
 // * Access connection-level information such as addresses and TLS status.
 // * Control connection lifecycle (e.g., close the connection).
-//
 message DynamicModuleNetworkFilter {
   // Specifies the shared-object level configuration.
   envoy.extensions.dynamic_modules.v3.DynamicModuleConfig dynamic_module_config = 1;
 
-  // The name for this filter configuration. This can be used to distinguish between different
-  // filter implementations inside a dynamic module. For example, a module can have completely
-  // different filter implementations. When Envoy receives this configuration, it passes the
-  // ``filter_name`` to the dynamic module's network filter config init function together with
-  // the ``filter_config``. That way a module can decide which in-module filter implementation
-  // to use based on the name at load time.
+  // The name for this filter configuration.
+  //
+  // This can be used to distinguish between different filter implementations inside a dynamic
+  // module. For example, a module can have completely different filter implementations. When Envoy
+  // receives this configuration, it passes the ``filter_name`` to the dynamic module's network
+  // filter config init function together with the ``filter_config``. That way a module can decide
+  // which in-module filter implementation to use based on the name at load time.
   string filter_name = 2;
 
-  // The configuration for the filter chosen by ``filter_name``. This is passed to the module's
-  // network filter initialization function. Together with the ``filter_name``, the module can
-  // decide which in-module filter implementation to use and fine-tune the behavior of the filter.
+  // The configuration for the filter chosen by ``filter_name``.
+  //
+  // This is passed to the module's network filter initialization function. Together with the
+  // ``filter_name``, the module can decide which in-module filter implementation to use and
+  // fine-tune the behavior of the filter.
   //
   // For example, if a module has two filter implementations, one for echo and one for rate
-  // limiting, ``filter_name`` is used to choose either echo or rate limiting. The ``filter_config``
-  // can be used to configure the echo behavior or the rate limiting parameters.
+  // limiting, ``filter_name`` is used to choose either echo or rate limiting. The
+  // ``filter_config`` can be used to configure the echo behavior or the rate limiting parameters.
   //
   // ``google.protobuf.Struct`` is serialized as JSON before passing it to the module.
   // ``google.protobuf.BytesValue`` and ``google.protobuf.StringValue`` are passed directly
@@ -69,8 +70,10 @@ message DynamicModuleNetworkFilter {
   //
   google.protobuf.Any filter_config = 3;
 
-  // Set true if the dynamic module is a terminal filter to use without an upstream connection.
+  // If ``true``, the dynamic module is a terminal filter to use without an upstream connection.
+  //
   // The dynamic module is responsible for creating and sending the response to downstream.
-  // If not specified, defaults to false.
+  //
+  // Defaults to ``false``.
   bool terminal_filter = 4;
 }