mirrors/qemu
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

qapi/common.py: Convert comments into docstrings, and elaborate

Browse Source 
As docstrings, they'll show up in documentation and IDE help.

The docstring style being targeted is the Sphinx documentation
style. Sphinx uses an extension of ReST with "domains". We use the
(implicit) Python domain, which supports a number of custom "info
fields". Those info fields are documented here:
https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#info-field-lists

Primarily, we use `:param X: descr`, `:return[s]: descr`, and `:raise[s]
Z: when`. Everything else is the Sphinx dialect of ReST.

(No, nothing checks or enforces this style that I am aware of. Sphinx
either chokes or succeeds, but does not enforce a standard of what is
otherwise inside the docstring. Pycharm does highlight when your param
fields are not aligned with the actual fields present. It does not
highlight missing return or exception statements. There is no existing
style guide I am aware of that covers a standard for a minimally
acceptable docstring. I am debating writing one.)

Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Eduardo Habkost <ehabkost@redhat.com>
Reviewed-by: Cleber Rosa <crosa@redhat.com>
Message-Id: <20201009161558.107041-17-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
This commit is contained in:
John Snow 2020-10-09 12:15:38 -04:00 committed by Markus Armbruster
parent d646b2a128
commit 1cc7398dfa
1 changed files with 40 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
scripts/qapi/common.py
View File

@ -15,15 +15,25 @@ import re
from typing import Optional, Sequence from typing import Optional, Sequence
#: Magic string that gets removed along with all space to its right.
EATSPACE = '\033EATSPACE.' EATSPACE = '\033EATSPACE.'
POINTER_SUFFIX = ' *' + EATSPACE POINTER_SUFFIX = ' *' + EATSPACE
_C_NAME_TRANS = str.maketrans('.-', '__') _C_NAME_TRANS = str.maketrans('.-', '__')
# ENUMName -> ENUM_NAME, EnumName1 -> ENUM_NAME1
# ENUM_NAME -> ENUM_NAME, ENUM_NAME1 -> ENUM_NAME1, ENUM_Name2 -> ENUM_NAME2
# ENUM24_Name -> ENUM24_NAME
def camel_to_upper(value: str) -> str: def camel_to_upper(value: str) -> str:
"""
Converts CamelCase to CAMEL_CASE.
Examples::
ENUMName -> ENUM_NAME
EnumName1 -> ENUM_NAME1
ENUM_NAME -> ENUM_NAME
ENUM_NAME1 -> ENUM_NAME1
ENUM_Name2 -> ENUM_NAME2
ENUM24_Name -> ENUM24_NAME
"""
c_fun_str = c_name(value, False) c_fun_str = c_name(value, False)
if value.isupper(): if value.isupper():
return c_fun_str return c_fun_str
@ -45,21 +55,33 @@ def camel_to_upper(value: str) -> str:
def c_enum_const(type_name: str, def c_enum_const(type_name: str,
const_name: str, const_name: str,
prefix: Optional[str] = None) -> str: prefix: Optional[str] = None) -> str:
"""
Generate a C enumeration constant name.
:param type_name: The name of the enumeration.
:param const_name: The name of this constant.
:param prefix: Optional, prefix that overrides the type_name.
"""
if prefix is not None: if prefix is not None:
type_name = prefix type_name = prefix
return camel_to_upper(type_name) + '_' + c_name(const_name, False).upper() return camel_to_upper(type_name) + '_' + c_name(const_name, False).upper()
# Map @name to a valid C identifier.
# If @protect, avoid returning certain ticklish identifiers (like
# C keywords) by prepending 'q_'.
#
# Used for converting 'name' from a 'name':'type' qapi definition
# into a generated struct member, as well as converting type names
# into substrings of a generated C function name.
# '__a.b_c' -> '__a_b_c', 'x-foo' -> 'x_foo'
# protect=True: 'int' -> 'q_int'; protect=False: 'int' -> 'int'
def c_name(name: str, protect: bool = True) -> str: def c_name(name: str, protect: bool = True) -> str:
"""
Map ``name`` to a valid C identifier.
Used for converting 'name' from a 'name':'type' qapi definition
into a generated struct member, as well as converting type names
into substrings of a generated C function name.
'__a.b_c' -> '__a_b_c', 'x-foo' -> 'x_foo'
protect=True: 'int' -> 'q_int'; protect=False: 'int' -> 'int'
:param name: The name to map.
:param protect: If true, avoid returning certain ticklish identifiers
(like C keywords) by prepending ``q_``.
"""
# ANSI X3J11/88-090, 3.1.1 # ANSI X3J11/88-090, 3.1.1
c89_words = set(['auto', 'break', 'case', 'char', 'const', 'continue', c89_words = set(['auto', 'break', 'case', 'char', 'const', 'continue',
'default', 'do', 'double', 'else', 'enum', 'extern', 'default', 'do', 'double', 'else', 'enum', 'extern',
@ -129,12 +151,16 @@ class Indentation:
self._level -= amount self._level -= amount
#: Global, current indent level for code generation.
indent = Indentation() indent = Indentation()
# Generate @code with @kwds interpolated.
# Obey indent, and strip EATSPACE.
def cgen(code: str, **kwds: object) -> str: def cgen(code: str, **kwds: object) -> str:
"""
Generate ``code`` with ``kwds`` interpolated.
Obey `indent`, and strip `EATSPACE`.
"""
raw = code % kwds raw = code % kwds
if indent: if indent:
raw = re.sub(r'^(?!(#|$))', str(indent), raw, flags=re.MULTILINE) raw = re.sub(r'^(?!(#|$))', str(indent), raw, flags=re.MULTILINE)