[PATCH 0/2] qapi: Documentation improvements

[PATCH 0/2] qapi: Documentation improvements

[Markus Armbruster]

Markus Armbruster (2):
  docs/devel/qapi-code-gen: Drop a duplicate paragraph
  docs/devel/qapi-code-gen: Belatedly document feature documentation

 docs/devel/qapi-code-gen.rst | 29 +++++++++++++++--------------
 1 file changed, 15 insertions(+), 14 deletions(-)

-- 
2.31.1

[PATCH 1/2] docs/devel/qapi-code-gen: Drop a duplicate paragraph

[Markus Armbruster]

Commit 55ec69f8b1 "docs/devel/qapi-code-gen.txt: Update to new rST
backend conventions" accidentally duplicated a paragraph.  Drop it.

Cc: Peter Maydell <peter.maydell@linaro.org>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 docs/devel/qapi-code-gen.rst | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
index b2569de486..1f6805a705 100644
--- a/docs/devel/qapi-code-gen.rst
+++ b/docs/devel/qapi-code-gen.rst
@@ -993,12 +993,6 @@ multiline argument descriptions.
 A 'Since: x.y.z' tagged section lists the release that introduced the
 definition.
 
-The text of a section can start on a new line, in
-which case it must not be indented at all.  It can also start
-on the same line as the 'Note:', 'Returns:', etc tag.  In this
-case if it spans multiple lines then second and subsequent
-lines must be indented to match the first.
-
 An 'Example' or 'Examples' section is automatically rendered
 entirely as literal fixed-width text.  In other sections,
 the text is formatted, and rST markup can be used.
-- 
2.31.1

Re: [PATCH 1/2] docs/devel/qapi-code-gen: Drop a duplicate paragraph

[Philippe Mathieu-Daudé]

On 10/26/21 13:10, Markus Armbruster wrote:
> Commit 55ec69f8b1 "docs/devel/qapi-code-gen.txt: Update to new rST
> backend conventions" accidentally duplicated a paragraph.  Drop it.
> 
> Cc: Peter Maydell <peter.maydell@linaro.org>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  docs/devel/qapi-code-gen.rst | 6 ------
>  1 file changed, 6 deletions(-)

Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>

Re: [PATCH 1/2] docs/devel/qapi-code-gen: Drop a duplicate paragraph

[John Snow]

[-- Attachment #1: Type: text/plain, Size: 1428 bytes --]

On Tue, Oct 26, 2021 at 7:10 AM Markus Armbruster <armbru@redhat.com> wrote:

> Commit 55ec69f8b1 "docs/devel/qapi-code-gen.txt: Update to new rST
> backend conventions" accidentally duplicated a paragraph.  Drop it.
>
>
Fixes: 55ec69f8b1
.... well, on second thought, that backport would have to go backwards
through a ReST conversion, so ... maybe not. Nevermind.


> Cc: Peter Maydell <peter.maydell@linaro.org>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
>

Reviewed-by: John Snow <jsnow@redhat.com>


> ---
>  docs/devel/qapi-code-gen.rst | 6 ------
>  1 file changed, 6 deletions(-)
>
> diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
> index b2569de486..1f6805a705 100644
> --- a/docs/devel/qapi-code-gen.rst
> +++ b/docs/devel/qapi-code-gen.rst
> @@ -993,12 +993,6 @@ multiline argument descriptions.
>  A 'Since: x.y.z' tagged section lists the release that introduced the
>  definition.
>
> -The text of a section can start on a new line, in
> -which case it must not be indented at all.  It can also start
> -on the same line as the 'Note:', 'Returns:', etc tag.  In this
> -case if it spans multiple lines then second and subsequent
> -lines must be indented to match the first.
> -
>  An 'Example' or 'Examples' section is automatically rendered
>  entirely as literal fixed-width text.  In other sections,
>  the text is formatted, and rST markup can be used.
> --
> 2.31.1
>
>

[-- Attachment #2: Type: text/html, Size: 2409 bytes --]

[PATCH 2/2] docs/devel/qapi-code-gen: Belatedly document feature documentation

[Markus Armbruster]

Commit 6a8c0b5102 "qapi: Add feature flags to struct types" neglected
to document how to document feature flags.  Make up for that.

Cc: Kevin Wolf <kwolf@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 docs/devel/qapi-code-gen.rst | 23 +++++++++++++++--------
 1 file changed, 15 insertions(+), 8 deletions(-)

diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
index 1f6805a705..4b79623f51 100644
--- a/docs/devel/qapi-code-gen.rst
+++ b/docs/devel/qapi-code-gen.rst
@@ -949,15 +949,16 @@ definition must have documentation.
 Definition documentation starts with a line naming the definition,
 followed by an optional overview, a description of each argument (for
 commands and events), member (for structs and unions), branch (for
-alternates), or value (for enums), and finally optional tagged
-sections.
+alternates), or value (for enums), a description of each feature (if
+any), and finally optional tagged sections.
 
-Descriptions of arguments can span multiple lines.  The description
-text can start on the line following the '\@argname:', in which case it
-must not be indented at all.  It can also start on the same line as
-the '\@argname:'.  In this case if it spans multiple lines then second
-and subsequent lines must be indented to line up with the first
-character of the first line of the description::
+The description of an argument or feature 'name' starts with
+'\@name:'.  The description text can start on the line following the
+'\@argname:', in which case it must not be indented at all.  It can
+also start on the same line as the '\@argname:'.  In this case if it
+spans multiple lines then second and subsequent lines must be indented
+to line up with the first character of the first line of the
+description::
 
  # @argone:
  # This is a two line description
@@ -979,6 +980,12 @@ The number of spaces between the ':' and the text is not significant.
 Extensions added after the definition was first released carry a
 '(since x.y.z)' comment.
 
+The feature descriptions must be preceded by a line "Features:", like
+this::
+
+  # Features:
+  # @feature: Description text
+
 A tagged section starts with one of the following words:
 "Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:".
 The section ends with the start of a new section.
-- 
2.31.1

Re: [PATCH 2/2] docs/devel/qapi-code-gen: Belatedly document feature documentation

[Kevin Wolf]

Am 26.10.2021 um 13:10 hat Markus Armbruster geschrieben:
> Commit 6a8c0b5102 "qapi: Add feature flags to struct types" neglected
> to document how to document feature flags.  Make up for that.
> 
> Cc: Kevin Wolf <kwolf@redhat.com>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  docs/devel/qapi-code-gen.rst | 23 +++++++++++++++--------
>  1 file changed, 15 insertions(+), 8 deletions(-)
> 
> diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
> index 1f6805a705..4b79623f51 100644
> --- a/docs/devel/qapi-code-gen.rst
> +++ b/docs/devel/qapi-code-gen.rst
> @@ -949,15 +949,16 @@ definition must have documentation.
>  Definition documentation starts with a line naming the definition,
>  followed by an optional overview, a description of each argument (for
>  commands and events), member (for structs and unions), branch (for
> -alternates), or value (for enums), and finally optional tagged
> -sections.
> +alternates), or value (for enums), a description of each feature (if
> +any), and finally optional tagged sections.
>  
> -Descriptions of arguments can span multiple lines.  The description
> -text can start on the line following the '\@argname:', in which case it
> -must not be indented at all.  It can also start on the same line as
> -the '\@argname:'.  In this case if it spans multiple lines then second
> -and subsequent lines must be indented to line up with the first
> -character of the first line of the description::
> +The description of an argument or feature 'name' starts with
> +'\@name:'.  The description text can start on the line following the
> +'\@argname:', in which case it must not be indented at all.  It can
> +also start on the same line as the '\@argname:'.  In this case if it
> +spans multiple lines then second and subsequent lines must be indented
> +to line up with the first character of the first line of the
> +description::

I'm confused. Are @name and @argname really two different things? What
does each one mean?

Kevin

Re: [PATCH 2/2] docs/devel/qapi-code-gen: Belatedly document feature documentation

[Markus Armbruster]

Kevin Wolf <kwolf@redhat.com> writes:

> Am 26.10.2021 um 13:10 hat Markus Armbruster geschrieben:
>> Commit 6a8c0b5102 "qapi: Add feature flags to struct types" neglected
>> to document how to document feature flags.  Make up for that.
>> 
>> Cc: Kevin Wolf <kwolf@redhat.com>
>> Signed-off-by: Markus Armbruster <armbru@redhat.com>
>> ---
>>  docs/devel/qapi-code-gen.rst | 23 +++++++++++++++--------
>>  1 file changed, 15 insertions(+), 8 deletions(-)
>> 
>> diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
>> index 1f6805a705..4b79623f51 100644
>> --- a/docs/devel/qapi-code-gen.rst
>> +++ b/docs/devel/qapi-code-gen.rst
>> @@ -949,15 +949,16 @@ definition must have documentation.
>>  Definition documentation starts with a line naming the definition,
>>  followed by an optional overview, a description of each argument (for
>>  commands and events), member (for structs and unions), branch (for
>> -alternates), or value (for enums), and finally optional tagged
>> -sections.
>> +alternates), or value (for enums), a description of each feature (if
>> +any), and finally optional tagged sections.
>>  
>> -Descriptions of arguments can span multiple lines.  The description
>> -text can start on the line following the '\@argname:', in which case it
>> -must not be indented at all.  It can also start on the same line as
>> -the '\@argname:'.  In this case if it spans multiple lines then second
>> -and subsequent lines must be indented to line up with the first
>> -character of the first line of the description::
>> +The description of an argument or feature 'name' starts with
>> +'\@name:'.  The description text can start on the line following the
>> +'\@argname:', in which case it must not be indented at all.  It can
>> +also start on the same line as the '\@argname:'.  In this case if it
>> +spans multiple lines then second and subsequent lines must be indented
>> +to line up with the first character of the first line of the
>> +description::
>
> I'm confused. Are @name and @argname really two different things? What
> does each one mean?

Editing screwup!  I meant to use @name every time.