[PATCH v2 01/33] qapi: Add documentation format validation

Vladimir Sementsov-Ogievskiy posted 33 patches 1 month ago
Maintainers: Eric Blake <eblake@redhat.com>, Markus Armbruster <armbru@redhat.com>, Mauro Carvalho Chehab <mchehab+huawei@kernel.org>, "Michael S. Tsirkin" <mst@redhat.com>, Igor Mammedov <imammedo@redhat.com>, Ani Sinha <anisinha@redhat.com>, Gerd Hoffmann <kraxel@redhat.com>, "Marc-André Lureau" <marcandre.lureau@redhat.com>, Kevin Wolf <kwolf@redhat.com>, Hanna Reitz <hreitz@redhat.com>, Paolo Bonzini <pbonzini@redhat.com>, "Daniel P. Berrangé" <berrange@redhat.com>, John Snow <jsnow@redhat.com>, Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>, Eduardo Habkost <eduardo@habkost.net>, Marcel Apfelbaum <marcel.apfelbaum@gmail.com>, "Philippe Mathieu-Daudé" <philmd@linaro.org>, Yanan Wang <wangyanan55@huawei.com>, Zhao Liu <zhao1.liu@intel.com>, Peter Xu <peterx@redhat.com>, Fabiano Rosas <farosas@suse.de>, Jason Wang <jasowang@redhat.com>, "Alex Bennée" <alex.bennee@linaro.org>, Jiri Pirko <jiri@resnulli.us>, Stefan Berger <stefanb@linux.vnet.ibm.com>, Stefan Hajnoczi <stefanha@redhat.com>, Mads Ynddal <mads@ynddal.dk>, Alex Williamson <alex.williamson@redhat.com>, "Cédric Le Goater" <clg@redhat.com>, Michael Roth <michael.roth@amd.com>, Kostiantyn Kostiuk <kkostiuk@redhat.com>
There is a newer version of this series
[PATCH v2 01/33] qapi: Add documentation format validation
Posted by Vladimir Sementsov-Ogievskiy 1 month ago
Add explicit validation for QAPI documentation formatting rules:

1. Lines must not exceed 70 columns in width (including '# ' prefix)
2. Sentences must be separated by two spaces

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 scripts/qapi/parser.py | 39 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 38 insertions(+), 1 deletion(-)

diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index 9fbf80a541..2c76686fc4 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -428,7 +428,44 @@ def get_doc_line(self) -> Optional[str]:
             return ''
         if self.val[1] != ' ':
             raise QAPIParseError(self, "missing space after #")
-        return self.val[2:].rstrip()
+
+        line = self.val[2:].rstrip()
+
+        self._validate_doc_line_format(line)
+
+        return line
+
+    def _validate_doc_line_format(self, line: str) -> None:
+        """
+        Validate documentation format rules for a single line:
+        1. Lines should not exceed 70 columns
+        2. Sentences should be separated by two spaces
+        """
+        # Check 70-column width rule
+        full_line_length = len(line) + 2  # "# " = 2 characters
+        if full_line_length > 70:
+            # Skip URL lines - they can't be broken
+            stripped_line = line.strip()
+            if (stripped_line.startswith(('http://', 'https://', 'ftp://')) and
+                ' ' not in stripped_line):
+                pass
+            else:
+                raise QAPIParseError(
+                    self, f"documentation line exceeds 70 columns "
+                    f"({full_line_length} columns): {line[:50]}..."
+                )
+
+        single_space_pattern = r'[.!?] [A-Z0-9]'
+        for m in list(re.finditer(single_space_pattern, line)):
+            left = line[0:m.start() + 1]
+            # Ignore abbreviations and numbered lists
+            if left.endswith('e.g.') or re.fullmatch(r' *\d\.', left):
+                continue
+            raise QAPIParseError(
+                 self, f"documentation has single space after sentence "
+                 f"ending. Use two spaces between sentences: "
+                 f"...{line[m.start()-5:m.end()+5]}..."
+            )
 
     @staticmethod
     def _match_at_name_colon(string: str) -> Optional[Match[str]]:
-- 
2.48.1