Message ID | 20200810195019.25427-7-peter.maydell@linaro.org |
---|---|
State | Accepted |
Headers | show |
Series | Convert QAPI doc comments to generate rST instead of texinfo | expand |
Peter Maydell <peter.maydell@linaro.org> writes: > doc-good.json tests doc comment parser corner cases. We're about to > largely replace it by a Sphinx extension, which will have different > corner cases. Tweak the test so it passes both with the old parser > and the Sphinx extension, by making it 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. Perhaps: * the rules on when and where indentation matters differ > * the '|' example syntax is going to go away entirely, so stop > testing it > > This will avoid the tests spuriously breaking when we tighten up the > parser code in the following commits. > > Reviewed-by: Richard Henderson <richard.henderson@linaro.org> > Reviewed-by: Markus Armbruster <armbru@redhat.com> > Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
On Fri, 4 Sep 2020 at 09:10, Markus Armbruster <armbru@redhat.com> wrote: > > Peter Maydell <peter.maydell@linaro.org> writes: > > > doc-good.json tests doc comment parser corner cases. We're about to > > largely replace it by a Sphinx extension, which will have different > > corner cases. Tweak the test so it passes both with the old parser > > and the Sphinx extension, by making it 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. Perhaps: > > * the rules on when and where indentation matters differ The commit message text here is the text you recommended in your review of v4 of this series... https://lists.gnu.org/archive/html/qemu-devel/2020-08/msg00988.html thanks -- PMM
diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json index 9da72a1f556..c6822145c49 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -12,25 +12,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 # - 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 @@ -68,7 +68,7 @@ ## # @Base: # @base1: -# the first member +# the first member ## { 'struct': 'Base', 'data': { 'base1': 'Enum' } } @@ -116,7 +116,7 @@ ## # @Alternate: # @i: an integer -# @b is undocumented +# @b is undocumented # # Features: # @alt-feat: a feature @@ -134,7 +134,7 @@ # @arg1: the first argument # # @arg2: the second -# argument +# argument # # Features: # @cmd-feat1: a feature @@ -143,6 +143,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 6757dd26a2f..4c24eb96486 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -74,25 +74,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 7f28fb7a0fb..12808989ffb 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