[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH v3 21/47] qapi/common.py: Convert comments into docstrings, and e
From: |
John Snow |
Subject: |
[PATCH v3 21/47] qapi/common.py: Convert comments into docstrings, and elaborate |
Date: |
Thu, 24 Sep 2020 20:28:34 -0400 |
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>
---
scripts/qapi/common.py | 53 +++++++++++++++++++++++++++++++-----------
1 file changed, 39 insertions(+), 14 deletions(-)
diff --git a/scripts/qapi/common.py b/scripts/qapi/common.py
index d1d39fdb4c..82266fe56a 100644
--- a/scripts/qapi/common.py
+++ b/scripts/qapi/common.py
@@ -14,15 +14,24 @@
import re
from typing import Optional, Sequence
+#: Sentinel value that causes all space to its right to be removed.
EATSPACE = '\033EATSPACE.'
POINTER_SUFFIX = ' *' + EATSPACE
_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:
+ """
+ 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)
if value.isupper():
return c_fun_str
@@ -44,21 +53,33 @@ def camel_to_upper(value: str) -> str:
def c_enum_const(type_name: str,
const_name: 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:
type_name = prefix
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:
+ """
+ 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
c89_words = set(['auto', 'break', 'case', 'char', 'const', 'continue',
'default', 'do', 'double', 'else', 'enum', 'extern',
@@ -128,12 +149,16 @@ def decrease(self, amount: int = 4) -> None:
self._level -= amount
+#: Global, current indent level for code generation.
indent = Indentation()
-# Generate @code with @kwds interpolated.
-# Obey indent, and strip EATSPACE.
def cgen(code: str, **kwds: object) -> str:
+ """
+ Generate ``code`` with ``kwds`` interpolated.
+
+ Obey `indent`, and strip `EATSPACE`.
+ """
raw = code % kwds
if indent:
raw = re.sub(r'^(?!(#|$))', str(indent), raw, flags=re.MULTILINE)
--
2.26.2
- [PATCH v3 19/47] qapi/common.py: check with pylint, (continued)
- [PATCH v3 19/47] qapi/common.py: check with pylint, John Snow, 2020/09/24
- [PATCH v3 23/47] qapi: establish mypy type-checking baseline, John Snow, 2020/09/24
- [PATCH v3 33/47] qapi/gen.py: Enable checking with mypy, John Snow, 2020/09/24
- [PATCH v3 25/47] qapi/events.py: Move comments into docstrings, John Snow, 2020/09/24
- [PATCH v3 16/47] qapi/common.py: Add indent manager, John Snow, 2020/09/24
- [PATCH v3 22/47] qapi/common.py: move build_params into gen.py, John Snow, 2020/09/24
- [PATCH v3 35/47] qapi/gen.py: update write() to be more idiomatic, John Snow, 2020/09/24
- [PATCH v3 27/47] qapi/commands.py: add type hint annotations, John Snow, 2020/09/24
- [PATCH v3 36/47] qapi/gen.py: delint with pylint, John Snow, 2020/09/24
- [PATCH v3 21/47] qapi/common.py: Convert comments into docstrings, and elaborate,
John Snow <=
- [PATCH v3 41/47] qapi/introspect.py: replace 'extra' dict with 'comment' argument, John Snow, 2020/09/24
- [PATCH v3 43/47] qapi/types.py: add type hint annotations, John Snow, 2020/09/24
- [PATCH v3 28/47] qapi/commands.py: enable checking with mypy, John Snow, 2020/09/24
- [PATCH v3 26/47] qapi/commands.py: Don't re-bind to variable of different type, John Snow, 2020/09/24
- [PATCH v3 29/47] qapi/source.py: add type hint annotations, John Snow, 2020/09/24
- [PATCH v3 34/47] qapi/gen.py: Remove unused parameter, John Snow, 2020/09/24
- [PATCH v3 18/47] qapi/common.py: Replace one-letter 'c' variable, John Snow, 2020/09/24
- [PATCH v3 30/47] qapi/source.py: delint with pylint, John Snow, 2020/09/24
- [PATCH v3 37/47] qapi/introspect.py: assert obj is a dict when features are given, John Snow, 2020/09/24