qemu/scripts/qapi/source.py
Markus Armbruster 0cec50119f qapi: Require member documentation (with loophole)
The QAPI generator forces you to document your stuff.  Except for
command arguments, event data, and members of enum and object types:
these the generator silently "documents" as "Not documented".

We can't require proper documentation there without first fixing all
the offenders.  We've always had too many offenders to pull that off.
Right now, we have more than 500.  Worse, we seem to fix old ones no
faster than we add new ones: in the past year, we fixed 22 ones, but
added 26 new ones.

To help arrest the backsliding, make missing documentation an error
unless the command, type, or event is in listed in new pragma
documentation-exceptions.

List all the current offenders: 117 commands and types in qapi/, and 9
in qga/.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240205074709.3613229-7-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2024-02-12 10:04:31 +01:00

74 lines
2.2 KiB
Python

#
# QAPI frontend source file info
#
# Copyright (c) 2019 Red Hat Inc.
#
# Authors:
# Markus Armbruster <armbru@redhat.com>
#
# This work is licensed under the terms of the GNU GPL, version 2.
# See the COPYING file in the top-level directory.
import copy
from typing import List, Optional, TypeVar
class QAPISchemaPragma:
# Replace with @dataclass in Python 3.7+
# pylint: disable=too-few-public-methods
def __init__(self) -> None:
# Are documentation comments required?
self.doc_required = False
# Commands whose names may use '_'
self.command_name_exceptions: List[str] = []
# Commands allowed to return a non-dictionary
self.command_returns_exceptions: List[str] = []
# Types, commands, and events with undocumented members
self.documentation_exceptions: List[str] = []
# Types whose member names may violate case conventions
self.member_name_exceptions: List[str] = []
class QAPISourceInfo:
T = TypeVar('T', bound='QAPISourceInfo')
def __init__(self, fname: str, parent: Optional['QAPISourceInfo']):
self.fname = fname
self.line = 1
self.parent = parent
self.pragma: QAPISchemaPragma = (
parent.pragma if parent else QAPISchemaPragma()
)
self.defn_meta: Optional[str] = None
self.defn_name: Optional[str] = None
def set_defn(self, meta: str, name: str) -> None:
self.defn_meta = meta
self.defn_name = name
def next_line(self: T) -> T:
info = copy.copy(self)
info.line += 1
return info
def loc(self) -> str:
return f"{self.fname}:{self.line}"
def in_defn(self) -> str:
if self.defn_name:
return "%s: In %s '%s':\n" % (self.fname,
self.defn_meta, self.defn_name)
return ''
def include_path(self) -> str:
ret = ''
parent = self.parent
while parent:
ret = 'In file included from %s:\n' % parent.loc() + ret
parent = parent.parent
return ret
def __str__(self) -> str:
return self.include_path() + self.in_defn() + self.loc()