John Snow <js...@redhat.com> writes:
> Presently, we never have any empty text entries for members. The next
> patch will explicitly generate such sections, so enable support for it
> in advance.
>
> The parser will generate placeholder sections to indicate undocumented
> members, but it's the qapidoc generator that's responsible for deciding
> what to do with that stub section.
>
> Signed-off-by: John Snow <js...@redhat.com>
> ---
> docs/sphinx/qapidoc.py | 4 ++--
> 1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
> index 96ac9f8620e..fec48fd01e1 100644
> --- a/docs/sphinx/qapidoc.py
> +++ b/docs/sphinx/qapidoc.py
> @@ -235,11 +235,11 @@ def visit_member(self, section: QAPIDoc.ArgSection) ->
> None:
> # TODO?: features for members (documented at entity-level,
> # but sometimes defined per-member. Should we add such
> # information to member descriptions when we can?)
> - assert section.text and section.member
> + assert section.member
> self.generate_field(
> self.member_field_type,
> section.member,
> - section.text,
> + section.text if section.text else "(Not Documented.)",
The old generator uses just "Not documented". I don't mind the period,
but the parenthesis looks awkward:
Members:
* limits ("ThrottleLimits", optional) -- limits to apply
for this throttle group
* x-iops-total ("int", optional) -- (Not Documented.)
The old generator has a comment
# TODO drop fallbacks when undocumented members are outlawed
Let's have it here as well.
> section.info,
> )
