Merge remote-tracking branch 'origin/topic/awelzel/zeekygen-param-doc-field'

* origin/topic/awelzel/zeekygen-param-doc-field:
  Bump doc submodule
  zeekygen: Render function parameters as :param x: instead of ❌

CHANGES

@@ -1,3 +1,20 @@
+6.0.0-dev.592 | 2023-05-17 09:02:09 +0200
+
+  * zeekygen: Render function parameters as :param x: instead of :x: (Arne Welzel, Corelight)
+
+    We're currently rendering parameter descriptions from .bif file into
+    the .rst as follows:
+
+        :cid: The connection identifier.
+
+        :aid: The analyzer ID.
+
+    Switch this to :param cid: instead so that we can have Sphinx deal with
+    this as param docfield and group all parameters into a single section.
+
+    Currently, having the bare :cid: style causes sphinx to treat it as an
+    unknown field type, capitalize it and render it.
+
 6.0.0-dev.589 | 2023-05-16 12:15:07 +0200
 
   * Move Spicy submodule from `auxil/spicy/spicy` to `auxil/spicy`.

NEWS

@@ -371,6 +371,10 @@ Changed Functionality
   previous behavior of not discarding state. Setting ``SMB::enable_state_clear``
   to ``F`` skips the script-layer state clearing logic.
 
+- Function parameters are rendered by Zeekygen as ``:param x`` rather than just
+  ``:x:``. This allows to group parameters Zeek's documentation.
+
+
 Removed Functionality
 ---------------------
 

VERSION

@@ -1 +1 @@
-6.0.0-dev.589
+6.0.0-dev.592

doc

@@ -1 +1 @@
-Subproject commit 00fc392ac2d61faa40e15689acab77a6d3dc773d
+Subproject commit cfd1c6a1e479cfeb1f08c379fc471bb8c7080de6

src/zeekygen/utils.cc

@@ -70,7 +70,7 @@ bool prettify_params(string& s)
 			if ( identifier == "Returns" )
 				subst = ":returns";
 			else
-				subst = ":" + identifier;
+				subst = ":param " + identifier;
 
 			s.replace(identifier_start_pos, identifier.size(), subst);
 			return true;

testing/btest/Baseline/doc.zeekygen.example/example.rst

@@ -260,7 +260,7 @@ Events
    link.  Use the see role instead: :zeek:see:`ZeekygenExample::a_function`.
    
 
-   :name: Describe the argument here.
+   :param name: Describe the argument here.
 
 Functions
 #########
@@ -275,11 +275,11 @@ Functions
    empty comments is optional, but improves readability of script.
    
 
-   :tag: Function arguments can be described
+   :param tag: Function arguments can be described
         like this.
    
 
-   :msg: Another param.
+   :param msg: Another param.
    
 
    :returns: Describe the return type here.

testing/btest/Baseline/doc.zeekygen.func-params/autogen-reST-func-params.rst

@@ -7,9 +7,9 @@
    This is a global function declaration.
    
 
-   :i: First param.
+   :param i: First param.
 
-   :j: Second param.
+   :param j: Second param.
    
 
    :returns: A string.
@@ -23,9 +23,9 @@
          This is a record field function.
          
 
-         :i: First param.
+         :param i: First param.
 
-         :j: Second param.
+         :param j: Second param.
          
 
          :returns: A string.

testing/btest/Baseline/doc.zeekygen.identifier/test.rst

@@ -212,11 +212,11 @@
    empty comments is optional, but improves readability of script.
    
 
-   :tag: Function arguments can be described
+   :param tag: Function arguments can be described
         like this.
    
 
-   :msg: Another param.
+   :param msg: Another param.
    
 
    :returns: Describe the return type here.
@@ -234,7 +234,7 @@
    link.  Use the see role instead: :zeek:see:`ZeekygenExample::a_function`.
    
 
-   :name: Describe the argument here.
+   :param name: Describe the argument here.
 
 .. zeek:id:: ZeekygenExample::function_without_proto
    :source-code: zeekygen/example.zeek 176 184