[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH v2 15/21] qapi/parser: add docstrings
From: |
John Snow |
Subject: |
[PATCH v2 15/21] qapi/parser: add docstrings |
Date: |
Tue, 11 May 2021 18:05:55 -0400 |
Signed-off-by: John Snow <jsnow@redhat.com>
---
scripts/qapi/parser.py | 68 ++++++++++++++++++++++++++++++++++++++++++
1 file changed, 68 insertions(+)
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index e80e0a7d965..ed543a2b7a4 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -47,7 +47,27 @@ def __init__(self, parser: 'QAPISchemaParser', msg: str):
class QAPISchemaParser:
+ """
+ Performs syntactic parsing of a QAPI schema source file.
+ Parses a JSON-esque schema file, See qapi-code-gen.txt section
+ "Schema Syntax" for more information. Grammatical validation
+ is handled later by `expr.check_exprs()`.
+
+ :param fname: Source filename.
+ :param previously_included:
+ The absolute pathnames of previously included source files,
+ if being invoked from another parser.
+ :param incl_info:
+ `QAPISourceInfo` belonging to the parent module.
+ ``None`` implies this is the root module.
+
+ :ivar exprs: Resulting parsed expressions.
+ :ivar docs: Resulting parsed documentation blocks.
+
+ :raise OSError: For problems opening the root schema document.
+ :raise QAPIError: For syntactic or semantic parsing errors.
+ """
def __init__(self,
fname: str,
previously_included: Optional[Set[str]] = None,
@@ -73,6 +93,11 @@ def __init__(self,
self._parse()
def _parse(self) -> None:
+ """
+ Parse the QAPI schema document.
+
+ :return: None. Results are stored in ``.exprs`` and ``.docs``.
+ """
cur_doc = None
# May raise OSError; allow the caller to handle it.
@@ -199,6 +224,49 @@ def check_list_str(name: str, value: object) -> List[str]:
raise QAPISemError(info, "unknown pragma '%s'" % name)
def accept(self, skip_comment: bool = True) -> None:
+ """Read and store the next token.
+
+ :param skip_comment:
+ When false, return COMMENT tokens ("#").
+ This is used when reading documentation blocks.
+
+ :return:
+ None. Several instance attributes are updated instead:
+
+ - ``.tok`` represents the token type. See below for values.
+ - ``.info`` describes the token's source location.
+ - ``.val`` is the token's value, if any. See below.
+ - ``.pos`` is the buffer index of the first character of
+ the token.
+
+ * Single-character tokens:
+
+ These are "{", "}", ":", ",", "[", and "]". ``.tok`` holds
+ the single character and ``.val`` is None.
+
+ * Multi-character tokens:
+
+ * COMMENT:
+
+ This token is not normally returned by the lexer, but it can
+ be when ``skip_comment`` is False. ``.tok`` is "#", and
+ ``.val`` is a string including all chars until end-of-line,
+ including the "#" itself.
+
+ * STRING:
+
+ ``.tok`` is "'", the single quote. ``.val`` contains the
+ string, excluding the surrounding quotes.
+
+ * TRUE and FALSE:
+
+ ``.tok`` is either "t" or "f", ``.val`` will be the
+ corresponding bool value.
+
+ * EOF:
+
+ ``.tok`` and ``.val`` will both be None at EOF.
+ """
while True:
self.tok = self.src[self.cursor]
self.pos = self.cursor
--
2.30.2
- Re: [PATCH v2 04/21] qapi/parser: factor parsing routine into method, (continued)
- [PATCH v2 09/21] qapi: add must_match helper, John Snow, 2021/05/11
- [PATCH v2 08/21] qapi/parser: Use @staticmethod where appropriate, John Snow, 2021/05/11
- [PATCH v2 10/21] qapi/parser: Fix token membership tests when token can be None, John Snow, 2021/05/11
- [PATCH v2 11/21] qapi/parser: Rework _check_pragma_list_of_str as a TypeGuard, John Snow, 2021/05/11
- [PATCH v2 12/21] qapi/parser: add type hint annotations, John Snow, 2021/05/11
- [PATCH v2 13/21] qapi/parser: Remove superfluous list comprehension, John Snow, 2021/05/11
- [PATCH v2 15/21] qapi/parser: add docstrings,
John Snow <=
- [PATCH v2 14/21] qapi/parser: allow 'ch' variable name, John Snow, 2021/05/11
- [PATCH v2 16/21] CHECKPOINT, John Snow, 2021/05/11
- [PATCH v2 19/21] qapi: [WIP] Import QAPIDoc from qapidoc Signed-off-by: John Snow <address@hidden>, John Snow, 2021/05/11
- [PATCH v2 18/21] qapi: [WIP] Add type ignores for qapidoc.py, John Snow, 2021/05/11
- [PATCH v2 21/21] qapi: [WIP] Enable linters on parser.py, John Snow, 2021/05/11
- [PATCH v2 20/21] qapi: [WIP] Add QAPIDocError, John Snow, 2021/05/11
- [PATCH v2 17/21] qapi: [WIP] Rip QAPIDoc out of parser.py, John Snow, 2021/05/11