RecordType:DescribeReST: Render RecordType using zeek:field directive

This is for zeek/zeek-docs#324.

src/Type.cc

@@ -1326,17 +1326,14 @@ void RecordType::DescribeFields(ODesc* d, bool func_args) const {
 }
 
 void RecordType::DescribeFieldsReST(ODesc* d, bool func_args) const {
-    if ( ! func_args )
-        d->PushIndent();
-
     for ( int i = 0; i < num_fields; ++i ) {
-        if ( i > 0 ) {
+        if ( func_args ) {
-            if ( func_args )
+            if ( i > 0 )
                 d->Add(", ");
-            else {
+        }
-                d->NL();
+        else {
-                d->NL();
+            d->NL();
-            }
+            d->NL();
         }
 
         const TypeDecl* td = FieldDecl(i);
@@ -1347,8 +1344,39 @@ void RecordType::DescribeFieldsReST(ODesc* d, bool func_args) const {
             if ( num_fields == 1 && util::streq(td->id, "va_args") && td->type->Tag() == TYPE_ANY )
                 // This was a BIF using variable argument list
                 d->Add("...");
-            else
+            else {
-                td->DescribeReST(d);
+                if ( func_args ) {
+                    td->DescribeReST(d);
+                }
+                else {
+                    // ReST rendering of a TypeDecl as zeek:field directive if
+                    // this is about rendering a proper record type and not
+                    // function parameters.
+                    //
+                    // Not sure why we're treating record types and function
+                    // signatures the same thing and than denote what it is
+                    // by passing around a bool. Open-code the field directive
+                    // rendering here.
+                    d->Add(".. zeek:field:: ");
+                    d->Add(td->id);
+                    d->Add(" ");
+                    if ( ! td->type->GetName().empty() ) {
+                        d->Add(":zeek:type:`");
+                        d->Add(td->type->GetName());
+                        d->Add("`");
+                    }
+                    else {
+                        td->type->DescribeReST(d, /*roles_only=*/true);
+                    }
+                    if ( td->attrs ) {
+                        d->SP();
+                        td->attrs->DescribeReST(d, /*shorten=*/true);
+                    }
+
+                    // Good thing ReST doesn't care too much about extra whitespace.
+                    d->NL();
+                }
+            }
         }
 
         if ( func_args )
@@ -1396,11 +1424,8 @@ void RecordType::DescribeFieldsReST(ODesc* d, bool func_args) const {
                 d->Add(cmnts[i].c_str());
         }
 
-        d->PopIndentNoNL();
+        d->PopIndent();
     }
-
-    if ( ! func_args )
-        d->PopIndentNoNL();
 }
 
 string RecordType::GetFieldDeprecationWarning(int field, bool has_check) const {

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

@@ -165,19 +165,28 @@ Types
 
    :Type: :zeek:type:`record`
 
-      field1: :zeek:type:`count`
-         Counts something.
 
-      field2: :zeek:type:`bool`
+   .. zeek:field:: field1 :zeek:type:`count`
-         Toggles something.
 
-      field3: :zeek:type:`ZeekygenExample::SimpleRecord`
+      Counts something.
-         Zeekygen automatically tracks types
+
-         and cross-references are automatically
+
-         inserted into generated docs.
+   .. zeek:field:: field2 :zeek:type:`bool`
+
+      Toggles something.
+
+
+   .. zeek:field:: field3 :zeek:type:`ZeekygenExample::SimpleRecord`
+
+      Zeekygen automatically tracks types
+      and cross-references are automatically
+      inserted into generated docs.
+
+
+   .. zeek:field:: msg :zeek:type:`string` :zeek:attr:`&default` = ``"blah"`` :zeek:attr:`&optional`
+
+      Attributes are self-documenting.
 
-      msg: :zeek:type:`string` :zeek:attr:`&default` = ``"blah"`` :zeek:attr:`&optional`
-         Attributes are self-documenting.
    :Attributes: :zeek:attr:`&redef`
 
    General documentation for a type "ComplexRecord" goes here.
@@ -187,11 +196,15 @@ Types
 
    :Type: :zeek:type:`record`
 
-      ts: :zeek:type:`time` :zeek:attr:`&log`
 
-      uid: :zeek:type:`string` :zeek:attr:`&log`
+   .. zeek:field:: ts :zeek:type:`time` :zeek:attr:`&log`
+
+
+   .. zeek:field:: uid :zeek:type:`string` :zeek:attr:`&log`
+
+
+   .. zeek:field:: status :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional`
 
-      status: :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional`
 
    An example record to be used with a logging stream.
    Nothing special about it.  If another script redefs this type
@@ -231,15 +244,22 @@ Types
 
    :Type: :zeek:type:`record`
 
-      field1: :zeek:type:`count`
-         Counts something.
 
-      field2: :zeek:type:`bool`
+   .. zeek:field:: field1 :zeek:type:`count`
-         Toggles something.
+
+      Counts something.
+
+
+   .. zeek:field:: field2 :zeek:type:`bool`
+
+      Toggles something.
+
+
+   .. zeek:field:: field_ext :zeek:type:`string` :zeek:attr:`&optional`
+
+      Document the extending field like this.
+      Or here, like this.
 
-      field_ext: :zeek:type:`string` :zeek:attr:`&optional`
-         Document the extending field like this.
-         Or here, like this.
 
    General documentation for a type "SimpleRecord" goes here.
    The way fields can be documented is similar to what's already seen

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

@@ -19,15 +19,18 @@
 
    :Type: :zeek:type:`record`
 
-      field_func: :zeek:type:`function` (i: :zeek:type:`int`, j: :zeek:type:`int`) : :zeek:type:`string`
-         This is a record field function.
-         
 
-         :param i: First param.
+   .. zeek:field:: field_func :zeek:type:`function` (i: :zeek:type:`int`, j: :zeek:type:`int`) : :zeek:type:`string`
 
-         :param j: Second param.
+      This is a record field function.
-         
+      
+
+      :param i: First param.
+
+      :param j: Second param.
+      
+
+      :returns: A string.
 
-         :returns: A string.
 
 

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

@@ -102,15 +102,22 @@
 
    :Type: :zeek:type:`record`
 
-      field1: :zeek:type:`count`
-         Counts something.
 
-      field2: :zeek:type:`bool`
+   .. zeek:field:: field1 :zeek:type:`count`
-         Toggles something.
+
+      Counts something.
+
+
+   .. zeek:field:: field2 :zeek:type:`bool`
+
+      Toggles something.
+
+
+   .. zeek:field:: field_ext :zeek:type:`string` :zeek:attr:`&optional`
+
+      Document the extending field like this.
+      Or here, like this.
 
-      field_ext: :zeek:type:`string` :zeek:attr:`&optional`
-         Document the extending field like this.
-         Or here, like this.
 
    General documentation for a type "SimpleRecord" goes here.
    The way fields can be documented is similar to what's already seen
@@ -121,19 +128,28 @@
 
    :Type: :zeek:type:`record`
 
-      field1: :zeek:type:`count`
-         Counts something.
 
-      field2: :zeek:type:`bool`
+   .. zeek:field:: field1 :zeek:type:`count`
-         Toggles something.
 
-      field3: :zeek:type:`ZeekygenExample::SimpleRecord`
+      Counts something.
-         Zeekygen automatically tracks types
+
-         and cross-references are automatically
+
-         inserted into generated docs.
+   .. zeek:field:: field2 :zeek:type:`bool`
+
+      Toggles something.
+
+
+   .. zeek:field:: field3 :zeek:type:`ZeekygenExample::SimpleRecord`
+
+      Zeekygen automatically tracks types
+      and cross-references are automatically
+      inserted into generated docs.
+
+
+   .. zeek:field:: msg :zeek:type:`string` :zeek:attr:`&default` = ``"blah"`` :zeek:attr:`&optional`
+
+      Attributes are self-documenting.
 
-      msg: :zeek:type:`string` :zeek:attr:`&default` = ``"blah"`` :zeek:attr:`&optional`
-         Attributes are self-documenting.
    :Attributes: :zeek:attr:`&redef`
 
    General documentation for a type "ComplexRecord" goes here.
@@ -143,11 +159,15 @@
 
    :Type: :zeek:type:`record`
 
-      ts: :zeek:type:`time` :zeek:attr:`&log`
 
-      uid: :zeek:type:`string` :zeek:attr:`&log`
+   .. zeek:field:: ts :zeek:type:`time` :zeek:attr:`&log`
+
+
+   .. zeek:field:: uid :zeek:type:`string` :zeek:attr:`&log`
+
+
+   .. zeek:field:: status :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional`
 
-      status: :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional`
 
    An example record to be used with a logging stream.
    Nothing special about it.  If another script redefs this type
@@ -248,8 +268,11 @@
 
    :Type: :zeek:type:`record`
 
-      field1: :zeek:type:`bool`
 
-      field2: :zeek:type:`count`
+   .. zeek:field:: field1 :zeek:type:`bool`
+
+
+   .. zeek:field:: field2 :zeek:type:`count`
+
 
 

testing/btest/Baseline/doc.zeekygen.records/autogen-reST-records.rst

@@ -4,9 +4,12 @@
 
    :Type: :zeek:type:`record`
 
-      field1: :zeek:type:`bool`
 
-      field2: :zeek:type:`count`
+   .. zeek:field:: field1 :zeek:type:`bool`
+
+
+   .. zeek:field:: field2 :zeek:type:`count`
+
 
 
 .. zeek:type:: TestRecord2
@@ -14,18 +17,27 @@
 
    :Type: :zeek:type:`record`
 
-      A: :zeek:type:`count`
-         document ``A``
 
-      B: :zeek:type:`bool`
+   .. zeek:field:: A :zeek:type:`count`
-         document ``B``
 
-      C: :zeek:type:`TestRecord1`
+      document ``A``
-         and now ``C``
+
-         is a declared type
+
+   .. zeek:field:: B :zeek:type:`bool`
+
+      document ``B``
+
+
+   .. zeek:field:: C :zeek:type:`TestRecord1`
+
+      and now ``C``
+      is a declared type
+
+
+   .. zeek:field:: D :zeek:type:`set` [:zeek:type:`count`, :zeek:type:`bool`]
+
+      sets/tables should show the index types
 
-      D: :zeek:type:`set` [:zeek:type:`count`, :zeek:type:`bool`]
-         sets/tables should show the index types
 
    Here's the ways records and record fields can be documented.
 

testing/btest/Baseline/doc.zeekygen.type-aliases/autogen-reST-type-aliases.rst

@@ -42,10 +42,14 @@
 
    :Type: :zeek:type:`record`
 
-      f1: :zeek:type:`ZeekygenTest::TypeAlias`
 
-      f2: :zeek:type:`ZeekygenTest::OtherTypeAlias`
+   .. zeek:field:: f1 :zeek:type:`ZeekygenTest::TypeAlias`
-
+
-      f3: :zeek:type:`bool`
+
+   .. zeek:field:: f2 :zeek:type:`ZeekygenTest::OtherTypeAlias`
+
+
+   .. zeek:field:: f3 :zeek:type:`bool`
+