John Snow <[email protected]> writes: > Section off the part of the spec that describes descriptions. > > Similarly to "Tagged sections", the concept of naming "Descriptions" > as a proper noun might also be something we'd like to sunset, but for > now I have retained the section. I believe the documentation itself is > entirely valid and useful, but we may want to come up with a term for > "arguments, members, branches, or values" as a group of concepts > instead - excising only "Features" as something that is different. > > Signed-off-by: John Snow <[email protected]> > --- > docs/devel/qapi-code-gen.rst | 22 ++++++++++++++++------ > 1 file changed, 16 insertions(+), 6 deletions(-) > > diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst > index 1897cde39cf..7e7b11d01df 100644 > --- a/docs/devel/qapi-code-gen.rst > +++ b/docs/devel/qapi-code-gen.rst > @@ -985,13 +985,23 @@ When documentation is required (see pragma_ > 'doc-required'), every > definition must have documentation. > > Definition documentation starts with a description naming the > -definition with an optional indented overview, a description of each > -argument (for commands and events), member (for structs and unions), > -branch (for alternates), or value (for enums), a description of each > -feature (if any), and finally optional tagged sections. > +definition with an optional indented overview, :ref:`descriptions > +<doc-descrip>` of each argument (for commands and events), member (for > +structs and unions), branch (for alternates), or value (for enums), a > +description of each feature (if any), and finally optional tagged > +sections.
Not this patch's fault: this isn't quite right. The order of tagged sections is left unspecified, which is fine now, but becomes a gap when your "qapi: enforce section ordering" series lands. "Details" sections aren't mentioned at all. > > -Descriptions start with '\@name:'. The description text must be > -indented like this:: > + > +.. _doc-descrip: > + > +Descriptions > +^^^^^^^^^^^^ > + > +Descriptions start with '\@name:'. These are used to document > +arguments (for commands and events), members (for structs and unions), > +branches (for alternates), or values (for enums). > + > +The description text must be indented like this:: > > # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed > # do eiusmod tempor incididunt ut labore et dolore magna aliqua.
