Re: [PATCH v4 04/18] tests/qapi/doc-good.json: Clean up markup

[Markus Armbruster]

The subject is a bit misleading.  The markup doesn't need cleanup.  It
purposefully tests corner cases of the doc comment parser.  For some of
them, the conversion to rST will change the meaning.  This commit tweaks
the test so it passes before and after the conversion.  Makes it a worse
test for the doc comment parser, which doesn't matter, because the code
in question is about to be deleted.

Peter Maydell <peter.maydell@linaro.org> writes:

> doc-good.json tests some oddities of markup that we don't want to
> accept.  Make them match the more restrictive rST syntax:
>
>  * in a single list the bullet types must all match
>  * lists must have leading and following blank lines
>  * indentation is important

Actually, indentation has always been important, but the conversion to
rST changes where and how it matters.

>  * the '|' example syntax is going to go away entirely, so stop
>    testing it

Before the series, we (try to) cover all doc markup here.

The series replaces the doc markup language by rST + a little extra.
The test must still cover the little extra then, and covering a bit of
rST to ensure basic sanity won't hurt.

Correct?

I'm asking because a "yes" explains why we can drop coverage without
replacement: it's appropriate when the markup in question is replaced by
rST.

> This will avoid the tests spuriously breaking when we tighten up the
> parser code in the following commits.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
> New patch in v2
> ---
>  tests/qapi-schema/doc-good.json | 25 +++++++++++++------------
>  tests/qapi-schema/doc-good.out  | 12 ++++++------
>  tests/qapi-schema/doc-good.texi | 12 +++---------
>  3 files changed, 22 insertions(+), 27 deletions(-)
>
> diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json
> index d992e713d97..a45dc22848c 100644
> --- a/tests/qapi-schema/doc-good.json
> +++ b/tests/qapi-schema/doc-good.json
> @@ -10,25 +10,25 @@
>  #
>  # *strong* _with emphasis_
>  # @var {in braces}
> +#
>  # * List item one
> -# - Two, multiple
> +# * Two, multiple
>  #   lines
>  #
> -# 3. Three
> -# Still in list
> +# * Three
> +#   Still in list
> +#
> +# Not in list
>  #
> -#   Not in list

This is an example for indentation becoming relevant where it wasn't
before.

The old doc markup language uses blank lines to terminate list items.
The new one uses indentation, which is more flexible.

>  # - Second list
> -# Note: still in list
> +#   Note: still in list
>  #
>  # Note: not in list
> +#
>  # 1. Third list
>  #    is numbered
>  #
> -# - another item
> -#
> -# | example
> -# | multiple lines
> +# 2. another item
>  #
>  # Returns: the King
>  # Since: the first age
> @@ -62,7 +62,7 @@
>  ##
>  # @Base:
>  # @base1:

Here, indentation is relevant even before the series: @base: is only
recognized as an argument section when it's not indented.

> -#   the first member
> +# the first member

Why do you need to unindent this line?

>  ##
>  { 'struct': 'Base', 'data': { 'base1': 'Enum' } }
>  
> @@ -101,7 +101,7 @@
>  ##
>  # @Alternate:
>  # @i: an integer
> -# @b is undocumented
> +#     @b is undocumented

Why do you need to indent this line?

>  ##
>  { 'alternate': 'Alternate',
>    'data': { 'i': 'int', 'b': 'bool' } }
> @@ -115,7 +115,7 @@
>  # @arg1: the first argument
>  #
>  # @arg2: the second
> -# argument
> +#        argument

Why do you need to indent this line?

>  #
>  # Features:
>  # @cmd-feat1: a feature
> @@ -124,6 +124,7 @@
>  # Returns: @Object
>  # TODO: frobnicate
>  # Notes:
> +#
>  # - Lorem ipsum dolor sit amet
>  # - Ut enim ad minim veniam
>  #
> diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
> index 4c9406a464d..9503a3a3178 100644
> --- a/tests/qapi-schema/doc-good.out
> +++ b/tests/qapi-schema/doc-good.out
> @@ -68,25 +68,25 @@ doc freeform
>  
>  *strong* _with emphasis_
>  @var {in braces}
> +
>  * List item one
> -- Two, multiple
> +* Two, multiple
>  lines
>  
> -3. Three
> +* Three
>  Still in list
>  
>  Not in list
> +
>  - Second list
>  Note: still in list
>  
>  Note: not in list
> +
>  1. Third list
>  is numbered
>  
> -- another item
> -
> -| example
> -| multiple lines
> +2. another item
>  
>  Returns: the King
>  Since: the first age
> diff --git a/tests/qapi-schema/doc-good.texi b/tests/qapi-schema/doc-good.texi
> index d4b15dabf03..1e8063c8579 100644
> --- a/tests/qapi-schema/doc-good.texi
> +++ b/tests/qapi-schema/doc-good.texi
> @@ -6,6 +6,7 @@
>  
>  @strong{strong} @emph{with emphasis}
>  @code{var} @{in braces@}
> +
>  @itemize @bullet
>  @item
>  List item one
> @@ -20,6 +21,7 @@ Still in list
>  @end itemize
>  
>  Not in list
> +
>  @itemize @minus
>  @item
>  Second list
> @@ -28,6 +30,7 @@ Note: still in list
>  @end itemize
>  
>  Note: not in list
> +
>  @enumerate
>  @item
>  Third list
> @@ -36,15 +39,6 @@ is numbered
>  @item
>  another item
>  
> -@example
> -example
> -@end example
> -
> -@example
> -multiple lines
> -@end example
> -
> -
>  @end enumerate
>  
>  Returns: the King