RecordType:DescribeReST: Render RecordType using zeek:field directive

This is for zeek/zeek-docs#324.

src/Type.cc

@@ -1326,18 +1326,15 @@ 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();
             d->NL();
         }
-        }
 
         const TypeDecl* td = FieldDecl(i);
 
@@ -1347,9 +1344,40 @@ 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 {
+                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 )
             continue;
@@ -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`
+
+   .. zeek:field:: field1 :zeek:type:`count`
+
       Counts something.
 
-      field2: :zeek:type:`bool`
+
+   .. zeek:field:: field2 :zeek:type:`bool`
+
       Toggles something.
 
-      field3: :zeek:type:`ZeekygenExample::SimpleRecord`
+
+   .. zeek:field:: field3 :zeek:type:`ZeekygenExample::SimpleRecord`
+
       Zeekygen automatically tracks types
       and cross-references are automatically
       inserted into generated docs.
 
-      msg: :zeek:type:`string` :zeek:attr:`&default` = ``"blah"`` :zeek:attr:`&optional`
+
+   .. zeek:field:: 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,16 +244,23 @@ Types
 
    :Type: :zeek:type:`record`
 
-      field1: :zeek:type:`count`
+
+   .. zeek:field:: field1 :zeek:type:`count`
+
       Counts something.
 
-      field2: :zeek:type:`bool`
+
+   .. zeek:field:: field2 :zeek:type:`bool`
+
       Toggles something.
 
-      field_ext: :zeek:type:`string` :zeek:attr:`&optional`
+
+   .. zeek:field:: 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
    for enums.

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

@@ -19,7 +19,9 @@
 
    :Type: :zeek:type:`record`
 
-      field_func: :zeek:type:`function` (i: :zeek:type:`int`, j: :zeek:type:`int`) : :zeek:type:`string`
+
+   .. zeek:field:: field_func :zeek:type:`function` (i: :zeek:type:`int`, j: :zeek:type:`int`) : :zeek:type:`string`
+
       This is a record field function.
       
 
@@ -31,3 +33,4 @@
       :returns: A string.
 
 
+

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

@@ -102,16 +102,23 @@
 
    :Type: :zeek:type:`record`
 
-      field1: :zeek:type:`count`
+
+   .. zeek:field:: field1 :zeek:type:`count`
+
       Counts something.
 
-      field2: :zeek:type:`bool`
+
+   .. zeek:field:: field2 :zeek:type:`bool`
+
       Toggles something.
 
-      field_ext: :zeek:type:`string` :zeek:attr:`&optional`
+
+   .. zeek:field:: 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
    for enums.
@@ -121,19 +128,28 @@
 
    :Type: :zeek:type:`record`
 
-      field1: :zeek:type:`count`
+
+   .. zeek:field:: field1 :zeek:type:`count`
+
       Counts something.
 
-      field2: :zeek:type:`bool`
+
+   .. zeek:field:: field2 :zeek:type:`bool`
+
       Toggles something.
 
-      field3: :zeek:type:`ZeekygenExample::SimpleRecord`
+
+   .. zeek:field:: field3 :zeek:type:`ZeekygenExample::SimpleRecord`
+
       Zeekygen automatically tracks types
       and cross-references are automatically
       inserted into generated docs.
 
-      msg: :zeek:type:`string` :zeek:attr:`&default` = ``"blah"`` :zeek:attr:`&optional`
+
+   .. zeek:field:: 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`
+
+   .. zeek:field:: A :zeek:type:`count`
+
       document ``A``
 
-      B: :zeek:type:`bool`
+
+   .. zeek:field:: B :zeek:type:`bool`
+
       document ``B``
 
-      C: :zeek:type:`TestRecord1`
+
+   .. zeek:field:: C :zeek:type:`TestRecord1`
+
       and now ``C``
       is a declared type
 
-      D: :zeek:type:`set` [:zeek:type:`count`, :zeek:type:`bool`]
+
+   .. zeek:field:: 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`
+