From f4dc24b527fc4a1b2809a78868a0c4f1a77db3cd Mon Sep 17 00:00:00 2001
From: Brad King <brad.king@kitware.com>
Date: Thu, 10 Oct 2024 11:09:36 -0400
Subject: [PATCH] FindProtobuf: Clarify protobuf_generate options documentation

---
 Modules/FindProtobuf.cmake | 78 ++++++++++++++++++++++++--------------
 1 file changed, 49 insertions(+), 29 deletions(-)

diff --git a/Modules/FindProtobuf.cmake b/Modules/FindProtobuf.cmake
index 197e71f961..5c6b37257e 100644
--- a/Modules/FindProtobuf.cmake
+++ b/Modules/FindProtobuf.cmake
@@ -108,20 +108,27 @@ Example:
 
   Add custom commands to process ``.proto`` files to C++::
 
-    protobuf_generate_cpp (<SRCS> <HDRS>
-        [DESCRIPTORS <DESC>] [EXPORT_MACRO <MACRO>] [<ARGN>...])
+    protobuf_generate_cpp (
+      <srcs-var> <hdrs-var>
+      [DESCRIPTORS <var>]
+      [EXPORT_MACRO <macro>]
+      [<proto-file>...])
 
-  ``SRCS``
+  ``<srcs-var>``
     Variable to define with autogenerated source files
-  ``HDRS``
+
+  ``<hdrs-var>``
     Variable to define with autogenerated header files
-  ``DESCRIPTORS``
+
+  ``DESCRIPTORS <var>``
     .. versionadded:: 3.10
       Variable to define with autogenerated descriptor files, if requested.
-  ``EXPORT_MACRO``
+
+  ``EXPORT_MACRO <macro>``
     is a macro which should expand to ``__declspec(dllexport)`` or
     ``__declspec(dllimport)`` depending on what is being compiled.
-  ``ARGN``
+
+  ``<proto-file>...``
     ``.proto`` files
 
 .. command:: protobuf_generate_python
@@ -130,11 +137,12 @@ Example:
 
   Add custom commands to process ``.proto`` files to Python::
 
-    protobuf_generate_python (<PY> [<ARGN>...])
+    protobuf_generate_python (<py-srcs-var> [<proto-file>...])
 
-  ``PY``
+  ``<py-srcs-var>``
     Variable to define with autogenerated Python files
-  ``ARGN``
+
+  ``<proto-file>...``
     ``.proto`` files
 
 .. command:: protobuf_generate
@@ -146,59 +154,71 @@ Example:
     protobuf_generate (
         TARGET <target>
         [LANGUAGE <lang>]
-        [OUT_VAR <out_var>]
+        [OUT_VAR <var>]
         [EXPORT_MACRO <macro>]
         [PROTOC_OUT_DIR <dir>]
         [PLUGIN <plugin>]
-        [PLUGIN_OPTIONS <plugin_options>]
-        [DEPENDENCIES <depends]
-        [PROTOS <protobuf_files>]
-        [IMPORT_DIRS <dirs>]
-        [GENERATE_EXTENSIONS <extensions>]
-        [PROTOC_OPTIONS <protoc_options>]
+        [PLUGIN_OPTIONS <plugin-options>]
+        [DEPENDENCIES <dependencies>]
+        [PROTOS <proto-file>...]
+        [IMPORT_DIRS <dir>...]
+        [GENERATE_EXTENSIONS <extension>...]
+        [PROTOC_OPTIONS <option>...]
         [APPEND_PATH])
 
   ``APPEND_PATH``
     A flag that causes the base path of all proto schema files to be added to
     ``IMPORT_DIRS``.
-  ``LANGUAGE``
+
+  ``LANGUAGE <lang>``
     A single value: cpp or python. Determines what kind of source files are
     being generated. Defaults to cpp.
-  ``OUT_VAR``
+
+  ``OUT_VAR <var>``
     Name of a CMake variable that will be filled with the paths to the generated
     source files.
-  ``EXPORT_MACRO``
+
+  ``EXPORT_MACRO <macro>``
     Name of a macro that is applied to all generated Protobuf message classes
     and extern variables. It can, for example, be used to declare DLL exports.
-  ``PROTOC_OUT_DIR``
+
+  ``PROTOC_OUT_DIR <dir>``
     Output directory of generated source files. Defaults to ``CMAKE_CURRENT_BINARY_DIR``.
-  ``PLUGIN``
+
+  ``PLUGIN <plugin>``
     .. versionadded:: 3.21
 
     An optional plugin executable. This could, for example, be the path to
     ``grpc_cpp_plugin``.
-  ``PLUGIN_OPTIONS``
+
+  ``PLUGIN_OPTIONS <plugin-options>``
     .. versionadded:: 3.28
 
     Additional options provided to the plugin, such as ``generate_mock_code=true``
     for the gRPC cpp plugin.
-  ``DEPENDENCIES``
+
+  ``DEPENDENCIES <dependencies>``
     .. versionadded:: 3.28
 
     Arguments forwarded to the ``DEPENDS`` of the underlying ``add_custom_command``
     invocation.
-  ``TARGET``
+
+  ``TARGET <target>``
     CMake target that will have the generated files added as sources.
-  ``PROTOS``
+
+  ``PROTOS <proto-file>...``
     List of proto schema files. If omitted, then every source file ending in *proto* of ``TARGET`` will be used.
-  ``IMPORT_DIRS``
+
+  ``IMPORT_DIRS <dir>...``
     A common parent directory for the schema files. For example, if the schema file is
     ``proto/helloworld/helloworld.proto`` and the import directory ``proto/`` then the
     generated files are ``${PROTOC_OUT_DIR}/helloworld/helloworld.pb.h`` and
     ``${PROTOC_OUT_DIR}/helloworld/helloworld.pb.cc``.
-  ``GENERATE_EXTENSIONS``
+
+  ``GENERATE_EXTENSIONS <extension>...``
     If LANGUAGE is omitted then this must be set to the extensions that protoc generates.
-  ``PROTOC_OPTIONS``
+
+  ``PROTOC_OPTIONS <option>...``
     .. versionadded:: 3.28
 
     Additional arguments that are forwarded to protoc.