diff --git a/src/Type.cc b/src/Type.cc index a9a072a20e..fcd2945168 100644 --- a/src/Type.cc +++ b/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(); - d->NL(); - } + } + else { + 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 - td->DescribeReST(d); + 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 ) @@ -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 { diff --git a/testing/btest/Baseline/doc.zeekygen.example/example.rst b/testing/btest/Baseline/doc.zeekygen.example/example.rst index aa2b0d3601..73cd6aa8f4 100644 --- a/testing/btest/Baseline/doc.zeekygen.example/example.rst +++ b/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` - Toggles something. + .. zeek:field:: field1 :zeek:type:`count` - field3: :zeek:type:`ZeekygenExample::SimpleRecord` - Zeekygen automatically tracks types - and cross-references are automatically - inserted into generated docs. + Counts something. + + + .. 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` - Toggles something. + .. zeek:field:: field1 :zeek:type:`count` + + 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 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 4cc37b9d7c..7b05862837 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 @@ -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. diff --git a/testing/btest/Baseline/doc.zeekygen.identifier/test.rst b/testing/btest/Baseline/doc.zeekygen.identifier/test.rst index b24dc870a3..7fe9165a03 100644 --- a/testing/btest/Baseline/doc.zeekygen.identifier/test.rst +++ b/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` - Toggles something. + .. zeek:field:: field1 :zeek:type:`count` + + 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` - Toggles something. + .. zeek:field:: field1 :zeek:type:`count` - field3: :zeek:type:`ZeekygenExample::SimpleRecord` - Zeekygen automatically tracks types - and cross-references are automatically - inserted into generated docs. + Counts something. + + + .. 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` + diff --git a/testing/btest/Baseline/doc.zeekygen.records/autogen-reST-records.rst b/testing/btest/Baseline/doc.zeekygen.records/autogen-reST-records.rst index 5d16ed1e77..138bca8116 100644 --- a/testing/btest/Baseline/doc.zeekygen.records/autogen-reST-records.rst +++ b/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` - document ``B`` + .. zeek:field:: A :zeek:type:`count` - C: :zeek:type:`TestRecord1` - and now ``C`` - is a declared type + document ``A`` + + + .. 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. diff --git a/testing/btest/Baseline/doc.zeekygen.type-aliases/autogen-reST-type-aliases.rst b/testing/btest/Baseline/doc.zeekygen.type-aliases/autogen-reST-type-aliases.rst index b1fb26cf28..ee0c18630c 100644 --- a/testing/btest/Baseline/doc.zeekygen.type-aliases/autogen-reST-type-aliases.rst +++ b/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` - - f3: :zeek:type:`bool` + .. zeek:field:: f1 :zeek:type:`ZeekygenTest::TypeAlias` + + + .. zeek:field:: f2 :zeek:type:`ZeekygenTest::OtherTypeAlias` + + + .. zeek:field:: f3 :zeek:type:`bool` +