[Qemu-commits] [qemu/qemu] f035b4: tests/qapi-schema: Demonstrate feature and enum do...

[Peter Maydell]

  Branch: refs/heads/master
  Home:   https://github.com/qemu/qemu
  Commit: f035b47e3f461e04e36e709aaad8bc8048b5f739
      
https://github.com/qemu/qemu/commit/f035b47e3f461e04e36e709aaad8bc8048b5f739
  Author: Markus Armbruster <address@hidden>
  Date:   2019-10-29 (Tue, 29 Oct 2019)

  Changed paths:
    M tests/Makefile.include
    A tests/qapi-schema/doc-bad-enum-member.err
    A tests/qapi-schema/doc-bad-enum-member.json
    A tests/qapi-schema/doc-bad-enum-member.out
    A tests/qapi-schema/doc-bad-feature.err
    A tests/qapi-schema/doc-bad-feature.json
    A tests/qapi-schema/doc-bad-feature.out
    A tests/qapi-schema/doc-undoc-feature.err
    A tests/qapi-schema/doc-undoc-feature.json
    A tests/qapi-schema/doc-undoc-feature.out

  Log Message:
  -----------
  tests/qapi-schema: Demonstrate feature and enum doc comment bugs

Add negative tests doc-bad-enum-member and doc-bad-feature to cover
documentation for nonexistent enum members and features, and test
doc-undoc-feature to cover features lacking documentation.  None of
them works.  To be fixed later in this series.

Signed-off-by: Markus Armbruster <address@hidden>
Message-Id: <address@hidden>


  Commit: 717cfcfae6df46c82b1ae191ec7ae6e0e288c914
      
https://github.com/qemu/qemu/commit/717cfcfae6df46c82b1ae191ec7ae6e0e288c914
  Author: Markus Armbruster <address@hidden>
  Date:   2019-10-29 (Tue, 29 Oct 2019)

  Changed paths:
    M tests/Makefile.include
    A tests/qapi-schema/doc-bad-boxed-command-arg.err
    A tests/qapi-schema/doc-bad-boxed-command-arg.json
    A tests/qapi-schema/doc-bad-boxed-command-arg.out
    A tests/qapi-schema/doc-bad-event-arg.err
    A tests/qapi-schema/doc-bad-event-arg.json
    A tests/qapi-schema/doc-bad-event-arg.out
    M tests/qapi-schema/doc-good.json
    M tests/qapi-schema/doc-good.out
    M tests/qapi-schema/doc-good.texi

  Log Message:
  -----------
  tests/qapi-schema: Demonstrate command and event doc comment bugs

Add negative tests doc-bad-boxed-command-arg and doc-bad-event-arg to
cover boxed and no arguments.  They demonstrate insufficient doc
comment checking.

Update positive test doc-good to cover boxed event arguments.  It
demonstrates the generated doc comment misses arguments.

These bugs will be fixed later in this series.

Signed-off-by: Markus Armbruster <address@hidden>
Message-Id: <address@hidden>


  Commit: f6401deb067457119278586fbb2a0c283382cfa4
      
https://github.com/qemu/qemu/commit/f6401deb067457119278586fbb2a0c283382cfa4
  Author: Markus Armbruster <address@hidden>
  Date:   2019-10-29 (Tue, 29 Oct 2019)

  Changed paths:
    M tests/qapi-schema/doc-good.json
    M tests/qapi-schema/doc-good.out
    M tests/qapi-schema/doc-good.texi

  Log Message:
  -----------
  tests/qapi-schema: Cover alternate documentation comments

Signed-off-by: Markus Armbruster <address@hidden>
Message-Id: <address@hidden>


  Commit: a0418a4a6b5bfc2f5d467af77a125dd7e4c4ca24
      
https://github.com/qemu/qemu/commit/a0418a4a6b5bfc2f5d467af77a125dd7e4c4ca24
  Author: Markus Armbruster <address@hidden>
  Date:   2019-10-29 (Tue, 29 Oct 2019)

  Changed paths:
    M tests/qapi-schema/doc-bad-feature.out
    M tests/qapi-schema/doc-good.out
    M tests/qapi-schema/doc-undoc-feature.out
    M tests/qapi-schema/test-qapi.py

  Log Message:
  -----------
  tests/qapi-schema: Fix feature documentation testing

Commit 8aa3a33e44 "tests/qapi-schema: Test for good feature lists in
structs" made test-qapi.py show features, but neglected to show their
documentation.  Fix that.

Signed-off-by: Markus Armbruster <address@hidden>
Message-Id: <address@hidden>


  Commit: 6d570ca10e3d7c628cdb5d8b8b5ea4fd3b994d9f
      
https://github.com/qemu/qemu/commit/6d570ca10e3d7c628cdb5d8b8b5ea4fd3b994d9f
  Author: Markus Armbruster <address@hidden>
  Date:   2019-10-29 (Tue, 29 Oct 2019)

  Changed paths:
    M qemu-deprecated.texi

  Log Message:
  -----------
  qemu-doc: Belatedly document QMP command deprecation

Commit 24fb413300 "qmp: Introduce blockdev-change-medium" (v2.5.0)
deprecated change.

Commit 2ff3025797 "migrate: move max-bandwidth and downtime-limit to
migrate_set_parameter" (v2.8.0) deprecated migrate_set_downtime and
migrate_set_speed.

These wre missed in commit eb22aeca65 "docs: document deprecation
policy & deprecated features in appendix" (v2.10.0).

Commit 73af8dd8d7 "migration: Make xbzrle_cache_size a migration
parameter" (v2.11.0) deprecated migrate-set-cache-size and
query-migrate-cache-size, but neglected to update qemu-doc.

Make up for that.

Signed-off-by: Markus Armbruster <address@hidden>
Message-Id: <address@hidden>


  Commit: b621a26040dd626cf9098c277e763f55fcfacf67
      
https://github.com/qemu/qemu/commit/b621a26040dd626cf9098c277e763f55fcfacf67
  Author: Markus Armbruster <address@hidden>
  Date:   2019-10-29 (Tue, 29 Oct 2019)

  Changed paths:
    M scripts/qapi/doc.py
    M tests/qapi-schema/doc-good.json
    M tests/qapi-schema/doc-good.out
    M tests/qapi-schema/doc-good.texi

  Log Message:
  -----------
  qapi: Implement boxed event argument documentation

Generate a reference "Arguments: the members of ...", just like we do
for commands since commit c2dd311cb7 "qapi2texi: Implement boxed
argument documentation".

No change to generated QMP documentation; we don't yet use boxed
events outside tests/.

Signed-off-by: Markus Armbruster <address@hidden>
Message-Id: <address@hidden>


  Commit: a4bd91d3f3d69414c9c76b856a0d69b12773503c
      
https://github.com/qemu/qemu/commit/a4bd91d3f3d69414c9c76b856a0d69b12773503c
  Author: Markus Armbruster <address@hidden>
  Date:   2019-10-29 (Tue, 29 Oct 2019)

  Changed paths:
    M scripts/qapi/doc.py

  Log Message:
  -----------
  qapi: De-duplicate entity documentation generation code

QAPISchemaGenDocVisitor.visit_command() duplicates texi_entity() for
its boxed arguments case.  The previous commit added another copy in
.visit_event().

Replace texi_entity() by texi_type() and texi_msg().  Use texi_msg()
for the boxed arguments case as well.

Signed-off-by: Markus Armbruster <address@hidden>
Message-Id: <address@hidden>


  Commit: ee1e6a1f6c830fd7530243a24c800063bc27a758
      
https://github.com/qemu/qemu/commit/ee1e6a1f6c830fd7530243a24c800063bc27a758
  Author: Markus Armbruster <address@hidden>
  Date:   2019-10-29 (Tue, 29 Oct 2019)

  Changed paths:
    M scripts/qapi/schema.py

  Log Message:
  -----------
  qapi: Split .connect_doc(), .check_doc() off .check()

Splitting documentation checking off the .check() methods makes them a
bit more focused, which is welcome, as some of them are pretty big.
It also prepares the ground for the following commits.

Signed-off-by: Markus Armbruster <address@hidden>
Message-Id: <address@hidden>


  Commit: 36a43905ffcac8767947626a6761df63fc020841
      
https://github.com/qemu/qemu/commit/36a43905ffcac8767947626a6761df63fc020841
  Author: Markus Armbruster <address@hidden>
  Date:   2019-10-29 (Tue, 29 Oct 2019)

  Changed paths:
    M scripts/qapi/schema.py
    M tests/qapi-schema/doc-bad-enum-member.err
    M tests/qapi-schema/doc-bad-enum-member.json
    M tests/qapi-schema/doc-bad-enum-member.out

  Log Message:
  -----------
  qapi: Fix enum doc comment checking

Enumeration type documentation comments are not checked, as
demonstrated by test doc-bad-enum-member.  This is because we neglect
to call self.doc.check() for enumeration types.  Messed up in
816a57cd6e "qapi: Fix detection of bogus member documentation".  Fix
it.

Signed-off-by: Markus Armbruster <address@hidden>
Message-Id: <address@hidden>


  Commit: 7faefad184201b10c2db4270b2bb93e2a5e9552b
      
https://github.com/qemu/qemu/commit/7faefad184201b10c2db4270b2bb93e2a5e9552b
  Author: Markus Armbruster <address@hidden>
  Date:   2019-10-29 (Tue, 29 Oct 2019)

  Changed paths:
    M scripts/qapi/schema.py

  Log Message:
  -----------
  qapi: Clean up doc comment checking for implicit union base

An object type's doc comment describes the type's members, less the
ones defined in a named base type.  Cases:

* Struct: the members are defined in 'data' and inherited from 'base'.
  Since the base type cannot be implicit, the doc comment describes
  just 'data'.

* Simple union: the only member is the implicit tag member @type, and
  the doc comment describes it.

* Flat union with implicit base type: the members are defined in
  'base', and the doc comment describes it.

* Flat union with named base type: the members are inherited from
  'base'.  The doc comment describes no members.

Before we can check a doc comment with .check_doc(), we need
.connect_doc() connect each of its "argument sections" to the member
it documents.

For structs and simple unions, this is straightforward: the members in
question are in .local_members, and .connect_doc() connects them.

For flat unions with a named base type, it's trivial: .local_members
is empty, and .connect_doc() does nothing.

For flat unions with an implicit base type, it's tricky.  We have
QAPISchema._make_implicit_object_type() forward the union's doc
comment to the implicit base type, so that the base type's
.connect_doc() connects the members.  The union's .connect_doc() does
nothing, as .local_members is empty.

Dirt effect: we check the doc comment twice, once for the union type,
and once for the implicit base type.

This is needlessly brittle and hard to understand.  Clean up as
follows.  Make the union's .connect_doc() connect an implicit base's
members itself.  Do not forward the union's doc comment to its
implicit base type.

Requires extending .connect_doc() so it can work with a doc comment
other than self.doc.  Add an optional argument for that.

Signed-off-by: Markus Armbruster <address@hidden>
Message-Id: <address@hidden>


  Commit: bf83f04e13063bb723fb8b9df789a3613c6d0ceb
      
https://github.com/qemu/qemu/commit/bf83f04e13063bb723fb8b9df789a3613c6d0ceb
  Author: Markus Armbruster <address@hidden>
  Date:   2019-10-29 (Tue, 29 Oct 2019)

  Changed paths:
    M qapi/net.json
    M scripts/qapi/doc.py
    M scripts/qapi/schema.py
    M tests/qapi-schema/doc-bad-boxed-command-arg.err
    M tests/qapi-schema/doc-bad-boxed-command-arg.json
    M tests/qapi-schema/doc-bad-boxed-command-arg.out
    M tests/qapi-schema/doc-bad-event-arg.err
    M tests/qapi-schema/doc-bad-event-arg.json
    M tests/qapi-schema/doc-bad-event-arg.out

  Log Message:
  -----------
  qapi: Fix doc comment checking for commands and events

When a command's 'data' is an object, its doc comment describes the
arguments defined there.  When 'data' names a type, the doc comment
does not describe arguments.  Instead, the doc generator inserts a
pointer to the named type.

An event's doc comment works the same.

We don't actually check doc comments for commands and events.
Instead, QAPISchema._def_command() forwards the doc comment to the
implicit argument type, where it gets checked.  Works because the
check only cares for the implicit argument type's members.

Not only is this needlessly hard to understand, it actually falls
apart in two cases:

* When 'data' is empty, there is nothing to forward to, and the doc
  comment remains unchecked.  Demonstrated by test doc-bad-event-arg.

* When 'data' names a type, we can't forward, as the type has its own
  doc comment.  The command or event's doc comment remains unchecked.
  Demonstrated by test doc-bad-boxed-command-arg.

The forwarding goes back to commit 069fb5b250 "qapi: Prepare for
requiring more complete documentation", put to use in commit
816a57cd6e "qapi: Fix detection of bogus member documentation".  That
fix was incomplete.

To fix this, make QAPISchemaCommand and QAPISchemaEvent check doc
comments, and drop the forwarding of doc comments to implicit argument
types.

Signed-off-by: Markus Armbruster <address@hidden>
Message-Id: <address@hidden>


  Commit: a710e1c8c3f1c0dda45608927d6f9cedd898c0d2
      
https://github.com/qemu/qemu/commit/a710e1c8c3f1c0dda45608927d6f9cedd898c0d2
  Author: Markus Armbruster <address@hidden>
  Date:   2019-10-29 (Tue, 29 Oct 2019)

  Changed paths:
    M scripts/qapi/schema.py

  Log Message:
  -----------
  qapi: Simplify ._make_implicit_object_type()

All callers now pass doc=None.  Drop the argument.

Signed-off-by: Markus Armbruster <address@hidden>
Message-Id: <address@hidden>


  Commit: 1192a4862b02b01c77415c3c04b5931e2b0b42bf
      
https://github.com/qemu/qemu/commit/1192a4862b02b01c77415c3c04b5931e2b0b42bf
  Author: Markus Armbruster <address@hidden>
  Date:   2019-10-29 (Tue, 29 Oct 2019)

  Changed paths:
    M scripts/qapi/schema.py

  Log Message:
  -----------
  qapi: Eliminate .check_doc() overrides

All sub-classes of QAPISchemaEntity now override .check_doc() the same
way, except for QAPISchemaType and and QAPISchemaArrayType.

Put the overrides' code in QAPISchemaEntity.check_doc(), and drop the
overrides.  QAPISchemaType doesn't care because it's abstract.
QAPISchemaArrayType doesn't care because its .doc is always None.

Signed-off-by: Markus Armbruster <address@hidden>
Message-Id: <address@hidden>


  Commit: c145bfda18f63c67f77ecbedbbd5a68fed2c4a4a
      
https://github.com/qemu/qemu/commit/c145bfda18f63c67f77ecbedbbd5a68fed2c4a4a
  Author: Markus Armbruster <address@hidden>
  Date:   2019-10-29 (Tue, 29 Oct 2019)

  Changed paths:
    M scripts/qapi/expr.py

  Log Message:
  -----------
  qapi: Fold normalize_if() into check_if()

check_if() is always called together with normalize_if().  Fold the
latter into the former.

Signed-off-by: Markus Armbruster <address@hidden>
Message-Id: <address@hidden>


  Commit: 2ce51ef68f243fb705c103498d8888d71532ccd3
      
https://github.com/qemu/qemu/commit/2ce51ef68f243fb705c103498d8888d71532ccd3
  Author: Markus Armbruster <address@hidden>
  Date:   2019-10-29 (Tue, 29 Oct 2019)

  Changed paths:
    M scripts/qapi/expr.py

  Log Message:
  -----------
  qapi: Fold normalize_features() into check_features()

check_features() is always called together with normalize_features():
the former in check_struct() and check_command(), the latter in their
caller check_exprs().  Fold the latter into the former.

Signed-off-by: Markus Armbruster <address@hidden>
Message-Id: <address@hidden>


  Commit: ad1ecfc6794bddd512f6f0ce400e3018d89e167b
      
https://github.com/qemu/qemu/commit/ad1ecfc6794bddd512f6f0ce400e3018d89e167b
  Author: Markus Armbruster <address@hidden>
  Date:   2019-10-29 (Tue, 29 Oct 2019)

  Changed paths:
    M scripts/qapi/expr.py

  Log Message:
  -----------
  qapi: Fold normalize_enum() into check_enum()

check_features() is always called together with normalize_features().
Fold the latter into the former.

Signed-off-by: Markus Armbruster <address@hidden>
Message-Id: <address@hidden>


  Commit: b3cdff10e5e82ba7b99c59ab3089883f6bb85ed8
      
https://github.com/qemu/qemu/commit/b3cdff10e5e82ba7b99c59ab3089883f6bb85ed8
  Author: Markus Armbruster <address@hidden>
  Date:   2019-10-29 (Tue, 29 Oct 2019)

  Changed paths:
    M scripts/qapi/schema.py

  Log Message:
  -----------
  qapi: Lift features into QAPISchemaEntity

Commit 6a8c0b5102 "qapi: Add feature flags to struct types" added
features to QAPISchemaObjectType.  Commit a95daa5093 "qapi: Add
feature flags to commands in qapi" added them to QAPISchemaCommand,
duplicating the code.  Tolerable, but the duplication will only get
worse as we add features to more definitions.

To de-duplicate, lift features from QAPISchemaObjectType and
QAPISchemaCommand into QAPISchemaEntity.

Signed-off-by: Markus Armbruster <address@hidden>
Message-Id: <address@hidden>


  Commit: e4def7875520aef0643e83698e397abe229a8953
      
https://github.com/qemu/qemu/commit/e4def7875520aef0643e83698e397abe229a8953
  Author: Markus Armbruster <address@hidden>
  Date:   2019-10-29 (Tue, 29 Oct 2019)

  Changed paths:
    M scripts/qapi/parser.py
    M tests/qapi-schema/doc-bad-alternate-member.err
    M tests/qapi-schema/doc-bad-boxed-command-arg.err
    M tests/qapi-schema/doc-bad-command-arg.err
    M tests/qapi-schema/doc-bad-enum-member.err
    M tests/qapi-schema/doc-bad-event-arg.err
    M tests/qapi-schema/doc-bad-union-member.err

  Log Message:
  -----------
  qapi: Polish reporting of bogus member documentation

Improve error messages from

    the following documented members are not in the declaration: a
    the following documented members are not in the declaration: aa, bb

to the more concise

    documented member 'a' does not exist
    documented members 'aa', 'bb' do not exist

Signed-off-by: Markus Armbruster <address@hidden>
Message-Id: <address@hidden>


  Commit: e151941d1b691402f7914750e025209b7839a1c0
      
https://github.com/qemu/qemu/commit/e151941d1b691402f7914750e025209b7839a1c0
  Author: Markus Armbruster <address@hidden>
  Date:   2019-10-29 (Tue, 29 Oct 2019)

  Changed paths:
    M scripts/qapi/parser.py
    M scripts/qapi/schema.py
    M tests/qapi-schema/doc-bad-feature.err
    M tests/qapi-schema/doc-bad-feature.json
    M tests/qapi-schema/doc-bad-feature.out
    M tests/qapi-schema/doc-undoc-feature.err
    M tests/qapi-schema/doc-undoc-feature.json
    M tests/qapi-schema/doc-undoc-feature.out

  Log Message:
  -----------
  qapi: Check feature documentation against the schema

Commit f3ed93d545 "qapi: Allow documentation for features" neglected
to check documentation against the schema.  Fix that: check them the
same way we check arguments.

Signed-off-by: Markus Armbruster <address@hidden>
Message-Id: <address@hidden>


  Commit: 16884391c750d0c5e863f55ad7aaaa146fc5181e
      
https://github.com/qemu/qemu/commit/16884391c750d0c5e863f55ad7aaaa146fc5181e
  Author: Peter Maydell <address@hidden>
  Date:   2019-10-29 (Tue, 29 Oct 2019)

  Changed paths:
    M qapi/net.json
    M qemu-deprecated.texi
    M scripts/qapi/doc.py
    M scripts/qapi/expr.py
    M scripts/qapi/parser.py
    M scripts/qapi/schema.py
    M tests/Makefile.include
    M tests/qapi-schema/doc-bad-alternate-member.err
    A tests/qapi-schema/doc-bad-boxed-command-arg.err
    A tests/qapi-schema/doc-bad-boxed-command-arg.json
    A tests/qapi-schema/doc-bad-boxed-command-arg.out
    M tests/qapi-schema/doc-bad-command-arg.err
    A tests/qapi-schema/doc-bad-enum-member.err
    A tests/qapi-schema/doc-bad-enum-member.json
    A tests/qapi-schema/doc-bad-enum-member.out
    A tests/qapi-schema/doc-bad-event-arg.err
    A tests/qapi-schema/doc-bad-event-arg.json
    A tests/qapi-schema/doc-bad-event-arg.out
    A tests/qapi-schema/doc-bad-feature.err
    A tests/qapi-schema/doc-bad-feature.json
    A tests/qapi-schema/doc-bad-feature.out
    M tests/qapi-schema/doc-bad-union-member.err
    M tests/qapi-schema/doc-good.json
    M tests/qapi-schema/doc-good.out
    M tests/qapi-schema/doc-good.texi
    A tests/qapi-schema/doc-undoc-feature.err
    A tests/qapi-schema/doc-undoc-feature.json
    A tests/qapi-schema/doc-undoc-feature.out
    M tests/qapi-schema/test-qapi.py

  Log Message:
  -----------
  Merge remote-tracking branch 'remotes/armbru/tags/pull-qapi-2019-10-29' into 
staging

QAPI patches for 2019-10-29

# gpg: Signature made Tue 29 Oct 2019 06:40:56 GMT
# gpg:                using RSA key 354BC8B3D7EB2A6B68674E5F3870B400EB918653
# gpg:                issuer "address@hidden"
# gpg: Good signature from "Markus Armbruster <address@hidden>" [full]
# gpg:                 aka "Markus Armbruster <address@hidden>" [full]
# Primary key fingerprint: 354B C8B3 D7EB 2A6B 6867  4E5F 3870 B400 EB91 8653

* remotes/armbru/tags/pull-qapi-2019-10-29:
  qapi: Check feature documentation against the schema
  qapi: Polish reporting of bogus member documentation
  qapi: Lift features into QAPISchemaEntity
  qapi: Fold normalize_enum() into check_enum()
  qapi: Fold normalize_features() into check_features()
  qapi: Fold normalize_if() into check_if()
  qapi: Eliminate .check_doc() overrides
  qapi: Simplify ._make_implicit_object_type()
  qapi: Fix doc comment checking for commands and events
  qapi: Clean up doc comment checking for implicit union base
  qapi: Fix enum doc comment checking
  qapi: Split .connect_doc(), .check_doc() off .check()
  qapi: De-duplicate entity documentation generation code
  qapi: Implement boxed event argument documentation
  qemu-doc: Belatedly document QMP command deprecation
  tests/qapi-schema: Fix feature documentation testing
  tests/qapi-schema: Cover alternate documentation comments
  tests/qapi-schema: Demonstrate command and event doc comment bugs
  tests/qapi-schema: Demonstrate feature and enum doc comment bugs

Signed-off-by: Peter Maydell <address@hidden>


Compare: https://github.com/qemu/qemu/compare/1cfe28cdcabd...16884391c750