0cec50119f
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>
74 lines
2.2 KiB
Python
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()
|