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

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

On Tue, Feb 20, 2024 at 05:06:42PM +0100, Markus Armbruster wrote:
> Daniel P. Berrangé <berrange@redhat.com> writes:
> 
> > 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.
> 
> True.
> 
> We could make it an error.  Can flag occurences in the middle of a
> free-form paragraph that happen to be at the beginning of a line, but
> that seems unlikely.
> 
> Of course, rST is full of similar syntactic traps anyway.  To quote
> Paolo, "I find it to be the Perl of ASCII-based markups."

Yes, probably not worth the hassle.

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 :|