John Snow <js...@redhat.com> writes: > When iterating all_sections, this is helpful to be able to distinguish > "members" from "features"; the only other way to do so is to > cross-reference these sections against QAPIDoc.args or QAPIDoc.features, > but if the desired end goal for QAPIDoc is to remove everything except > all_sections, we need *something* accessible to distinguish them. > > To keep types simple, add this semantic parameter to the base Section > and not just ArgSection; we can use this to filter out paragraphs and > tagged sections, too. > > Signed-off-by: John Snow <js...@redhat.com> > --- > scripts/qapi/parser.py | 25 ++++++++++++++++--------- > 1 file changed, 16 insertions(+), 9 deletions(-) > > diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py > index 161768b8b96..cf4cbca1c1f 100644 > --- a/scripts/qapi/parser.py > +++ b/scripts/qapi/parser.py > @@ -613,21 +613,27 @@ class QAPIDoc: > > class Section: > # pylint: disable=too-few-public-methods > - def __init__(self, info: QAPISourceInfo, > - tag: Optional[str] = None): > + def __init__( > + self, > + info: QAPISourceInfo, > + tag: Optional[str] = None, > + kind: str = 'paragraph', > + ): > # section source info, i.e. where it begins > self.info = info > # section tag, if any ('Returns', '@name', ...) > self.tag = tag > # section text without tag > self.text = '' > + # section type - {paragraph, feature, member, tagged} > + self.kind = kind
Hmm. .kind is almost redundant with .tag. Untagged section: .kind is 'paragraph', .tag is None Member description: .kind is 'member', .tag matches @NAME Feature description: .kind is 'feature', .tag matches @NAME Tagged section: .kind is 'tagged', .tag matches r'Returns|Errors|Since|Notes?|Examples?|TODO' .kind can directly be derived from .tag except for member and feature descriptions. And you want to tell these two apart in a straightforward manner in later patches, as you explain in your commit message. If .kind is 'member' or 'feature', then self must be an ArgSection. Worth a comment? An assertion? Some time back, I considered changing .tag for member and feature descriptions to suitable strings, like your 'member' and 'feature', and move the member / feature name into ArgSection. I didn't, because the benefit wasn't worth the churn at the time. Perhaps it's worth it now. Would it result in simpler code than your solution? Terminology nit: the section you call 'paragraph' isn't actually a paragraph: it could be several paragraphs. Best to call it 'untagged', as in .ensure_untagged_section(). > > def append_line(self, line: str) -> None: > self.text += line + '\n' > > class ArgSection(Section): > - def __init__(self, info: QAPISourceInfo, tag: str): > - super().__init__(info, tag) > + def __init__(self, info: QAPISourceInfo, tag: str, kind: str): > + super().__init__(info, tag, kind) > self.member: Optional['QAPISchemaMember'] = None > > def connect(self, member: 'QAPISchemaMember') -> None: [...]