Re: [PATCH 11/16] qapi: Recognize section tags and 'Features:' only after blank line

["Daniel P. Berrangé" <berrange@redhat.com>]

On Fri, Feb 16, 2024 at 03:58:35PM +0100, Markus Armbruster wrote:
> Putting a blank line before section tags and 'Features:' is good,
> existing practice.  Enforce it.
> 
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  docs/devel/qapi-code-gen.rst                 | 15 +++++++++------
>  scripts/qapi/parser.py                       | 11 ++++++++---
>  tests/qapi-schema/doc-duplicated-return.err  |  2 +-
>  tests/qapi-schema/doc-duplicated-return.json |  1 +
>  tests/qapi-schema/doc-duplicated-since.err   |  2 +-
>  tests/qapi-schema/doc-duplicated-since.json  |  1 +
>  tests/qapi-schema/doc-good.json              |  9 +++++++++
>  tests/qapi-schema/doc-invalid-return.err     |  2 +-
>  tests/qapi-schema/doc-invalid-return.json    |  1 +
>  9 files changed, 32 insertions(+), 12 deletions(-)

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>


> @@ -574,9 +577,11 @@ def end_comment(self) -> None:
>      def _match_at_name_colon(string: str) -> Optional[Match[str]]:
>          return re.match(r'@([^:]*): *', string)
>  
> -    @staticmethod
> -    def _match_section_tag(string: str) -> Optional[Match[str]]:
> -        return re.match(r'(Returns|Since|Notes?|Examples?|TODO): *', string)
> +    def _match_section_tag(self, string: str) -> Optional[Match[str]]:
> +        if not self._first_line_in_paragraph:
> +            return None
> +        return re.match(r'(Returns|Since|Notes?|Examples?|TODO): *',
> +                        string)

I guess I have a minor worry that we're silently ignoring
these tags when there's no blank line. Could result in
docs silently rendering in the wrong way if (when) someone
forgets the blank line.


With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|