From 2007eeae1b2020e890a5d3359b77386196628848 Mon Sep 17 00:00:00 2001 From: Arne Welzel Date: Tue, 16 May 2023 20:13:34 +0200 Subject: [PATCH 1/2] zeekygen: Render function parameters as :param x: instead of :x: 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. --- src/zeekygen/utils.cc | 2 +- testing/btest/Baseline/doc.zeekygen.example/example.rst | 6 +++--- .../doc.zeekygen.func-params/autogen-reST-func-params.rst | 8 ++++---- testing/btest/Baseline/doc.zeekygen.identifier/test.rst | 6 +++--- 4 files changed, 11 insertions(+), 11 deletions(-) diff --git a/src/zeekygen/utils.cc b/src/zeekygen/utils.cc index 05779dc1bc..094cd58424 100644 --- a/src/zeekygen/utils.cc +++ b/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; diff --git a/testing/btest/Baseline/doc.zeekygen.example/example.rst b/testing/btest/Baseline/doc.zeekygen.example/example.rst index 12e2f23aa6..aa2b0d3601 100644 --- a/testing/btest/Baseline/doc.zeekygen.example/example.rst +++ b/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. diff --git a/testing/btest/Baseline/doc.zeekygen.func-params/autogen-reST-func-params.rst b/testing/btest/Baseline/doc.zeekygen.func-params/autogen-reST-func-params.rst index 598c449a66..4cc37b9d7c 100644 --- a/testing/btest/Baseline/doc.zeekygen.func-params/autogen-reST-func-params.rst +++ b/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. diff --git a/testing/btest/Baseline/doc.zeekygen.identifier/test.rst b/testing/btest/Baseline/doc.zeekygen.identifier/test.rst index a63a5439b7..219c92da8b 100644 --- a/testing/btest/Baseline/doc.zeekygen.identifier/test.rst +++ b/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 From 09876cfc845abfc75374e023ce38515d5a2550ce Mon Sep 17 00:00:00 2001 From: Arne Welzel Date: Tue, 16 May 2023 21:02:50 +0200 Subject: [PATCH 2/2] Bump doc submodule This bumps to a version that understands and renders :param x: in a nicer way than what we have now (IMO). --- doc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc b/doc index 00fc392ac2..08787aefff 160000 --- a/doc +++ b/doc @@ -1 +1 @@ -Subproject commit 00fc392ac2d61faa40e15689acab77a6d3dc773d +Subproject commit 08787aefff89b1eae8f631bdf130aa2267dd0378