[Qemu-commits] [qemu/qemu] 2a7d95: qapi: Expand documentation for LostTickPolicy

[Peter Maydell]

  Branch: refs/heads/master
  Home:   https://github.com/qemu/qemu
  Commit: 2a7d957596786404c4ed16b089273de95a9580ad
      
https://github.com/qemu/qemu/commit/2a7d957596786404c4ed16b089273de95a9580ad
  Author: Andrea Bolognani <address@hidden>
  Date:   2020-02-14 (Fri, 14 Feb 2020)

  Changed paths:
    M qapi/misc.json

  Log Message:
  -----------
  qapi: Expand documentation for LostTickPolicy

The current documentation is fairly terse and not easy to decode
for someone who's not intimately familiar with the inner workings
of timer devices. Expand on it by providing a somewhat verbose
description of what behavior each policy will result in, as seen
from both the guest OS and host point of view.

Signed-off-by: Andrea Bolognani <address@hidden>
Message-Id: <address@hidden>
Reviewed-by: Ján Tomko <address@hidden>
Reviewed-by: Andrew Jones <address@hidden>
Signed-off-by: Markus Armbruster <address@hidden>


  Commit: 2eb054c237d0b5427f62499f3c31e90cf87821d7
      
https://github.com/qemu/qemu/commit/2eb054c237d0b5427f62499f3c31e90cf87821d7
  Author: Peter Maydell <address@hidden>
  Date:   2020-02-14 (Fri, 14 Feb 2020)

  Changed paths:
    M Makefile
    M configure

  Log Message:
  -----------
  configure: Allow user to specify sphinx-build binary

Currently we insist on using 'sphinx-build' from the $PATH;
allow the user to specify the binary to use. This will be
more useful as we become pickier about the capabilities
we require (eg needing a Python 3 sphinx-build).

Signed-off-by: Peter Maydell <address@hidden>
Reviewed-by: Alex Bennée <address@hidden>
Reviewed-by: Wainer dos Santos Moschetta <address@hidden>
Message-Id: <address@hidden>
Signed-off-by: Markus Armbruster <address@hidden>


  Commit: 903458c8abdb5f6b2393a167a077899ab3e1a36c
      
https://github.com/qemu/qemu/commit/903458c8abdb5f6b2393a167a077899ab3e1a36c
  Author: Markus Armbruster <address@hidden>
  Date:   2020-02-15 (Sat, 15 Feb 2020)

  Changed paths:
    M configure

  Log Message:
  -----------
  configure: Pick sphinx-build-3 when available

The next commit will require a sphinx-build that uses Python 3.  On
some systems, sphinx-build is fine, on others you need to use
sphinx-build-3.  To keep things working out of the box on both kinds
of systems, try sphinx-build-3, then sphinx-build.

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


  Commit: 758b617af804b7163eb28be2d44ce526580c06f7
      
https://github.com/qemu/qemu/commit/758b617af804b7163eb28be2d44ce526580c06f7
  Author: Peter Maydell <address@hidden>
  Date:   2020-02-15 (Sat, 15 Feb 2020)

  Changed paths:
    M configure
    M docs/conf.py

  Log Message:
  -----------
  configure: Check that sphinx-build is using Python 3

Currently configure's has_sphinx_build() check simply runs a dummy
sphinx-build and either passes or fails.  This means that "no
sphinx-build at all" and "sphinx-build exists but is too old" are
both reported the same way.

Further, we want to assume that all the Python we write is running
with at least Python 3.5; configure checks that for our scripts, but
Sphinx extensions run with whatever Python version sphinx-build
itself is using.

Add a check to our conf.py which makes sphinx-build fail if it would
be running our extensions with an old Python, and handle this
in configure so we can report failure helpfully to the user.
This will mean that configure --enable-docs will fail like this
if the sphinx-build provided is not suitable:

Warning: sphinx-build exists but it is either too old or uses too old a Python 
version

ERROR: User requested feature docs
       configure was not able to find it.
       Install texinfo, Perl/perl-podlators and a Python 3 version of 
python-sphinx

(As usual, the default is to simply not build the docs, as we would
if sphinx-build wasn't present at all.)

Signed-off-by: Peter Maydell <address@hidden>
Reviewed-by: Alex Bennée <address@hidden>
Reviewed-by: Wainer dos Santos Moschetta <address@hidden>
Message-Id: <address@hidden>
Signed-off-by: Markus Armbruster <address@hidden>


  Commit: 18064a62432c0834fa5b89691d3c666870b48a6c
      
https://github.com/qemu/qemu/commit/18064a62432c0834fa5b89691d3c666870b48a6c
  Author: Peter Maydell <address@hidden>
  Date:   2020-02-15 (Sat, 15 Feb 2020)

  Changed paths:
    M Makefile

  Log Message:
  -----------
  Makefile: Fix typo in dependency list for interop manpages

Fix a typo in the dependency list for the manpages built from the
'interop' manual, which meant we were accidentally not including
the .hx file in the dependency list.

Fixes: e13c59fa4414215500e6
Signed-off-by: Peter Maydell <address@hidden>
Reviewed-by: Philippe Mathieu-Daudé <address@hidden>
Message-Id: <address@hidden>
Signed-off-by: Markus Armbruster <address@hidden>


  Commit: 72ec8bf362b24ebbd45452c298a3b14fb617eebb
      
https://github.com/qemu/qemu/commit/72ec8bf362b24ebbd45452c298a3b14fb617eebb
  Author: Peter Maydell <address@hidden>
  Date:   2020-02-15 (Sat, 15 Feb 2020)

  Changed paths:
    M qga/qapi-schema.json

  Log Message:
  -----------
  qga/qapi-schema.json: Fix missing '-' in GuestDiskBusType doc comment

The doc comment for GuestDiskBusType doesn't match up with the
enumeration because of a missing hyphen in 'file-backed-virtual'.
This means the docs are rendered wrongly:
       "virtual"
           Win virtual bus type "file-backed" virtual: Win file-backed bus type

       "file-backed-virtual"
           Not documented

Add the missing hyphen.

Signed-off-by: Peter Maydell <address@hidden>
Reviewed-by: Eric Blake <address@hidden>
Reviewed-by: Markus Armbruster <address@hidden>
Message-Id: <address@hidden>
Signed-off-by: Markus Armbruster <address@hidden>


  Commit: 883aff68a7d6797a06bac94f631db3439b11a60e
      
https://github.com/qemu/qemu/commit/883aff68a7d6797a06bac94f631db3439b11a60e
  Author: Peter Maydell <address@hidden>
  Date:   2020-02-15 (Sat, 15 Feb 2020)

  Changed paths:
    M qga/qapi-schema.json

  Log Message:
  -----------
  qga/qapi-schema.json: Fix indent level on doc comments

The current doc generation doesn't care much about indentation levels,
but we would like to switch to an rST format, and rST does care about
indentation.

Make the doc comments more strongly consistent about indentation
for multiline constructs like:

@arg: description line 1
      description line 2

Returns: line one
         line 2

so that there is always exactly one space after the colon, and
subsequent lines align with the first.

This commit is a purely whitespace change, and it does not alter the
generated .texi files (because the texi generation code strips away
all the extra whitespace).  This does mean that we end up with some
over-length lines.

Note that when the documentation for an argument fits on a single
line like this:

@arg: one line only

then stray extra spaces after the ':' don't affect the rST output, so
I have not attempted to methodically fix them, though the preference
is a single space here too.

Signed-off-by: Peter Maydell <address@hidden>
Reviewed-by: Markus Armbruster <address@hidden>
Message-Id: <address@hidden>
[Commit message tweaked]
Signed-off-by: Markus Armbruster <address@hidden>


  Commit: a7b6e8964142264f4791fd03f6e5a4756a3fc4af
      
https://github.com/qemu/qemu/commit/a7b6e8964142264f4791fd03f6e5a4756a3fc4af
  Author: Peter Maydell <address@hidden>
  Date:   2020-02-15 (Sat, 15 Feb 2020)

  Changed paths:
    M qga/qapi-schema.json

  Log Message:
  -----------
  qga/qapi-schema.json: minor format fixups for rST

We would like to switch the doc comments to rST format, and rST
requires a blank line before the start of a bulleted or enumerated
list. Two places in qapi-schema.json were missing this blank line.

Some places were using an indented line as a sort of single-item
bulleted list, which in the Texinfo output comes out all run
onto a single line; use a real bulleted list instead.

Some places unnecessarily indented lists, which confuses rST.

guest-fstrim:minimum's documentation was indented the
right amount to share a line with @minimum, but wasn't
actually doing so.

The indent on the bulleted list in the guest-set-vcpus
Returns section meant rST misindented it.

Changes to the generated Texinfo are very minor (the new
bulleted lists, and a few extra blank lines).

Signed-off-by: Peter Maydell <address@hidden>
Message-Id: <address@hidden>
[Commit message tweaked]
Signed-off-by: Markus Armbruster <address@hidden>


  Commit: 0a940d66de9590566c09e3bfab539d5cbe9481d9
      
https://github.com/qemu/qemu/commit/0a940d66de9590566c09e3bfab539d5cbe9481d9
  Author: Peter Maydell <address@hidden>
  Date:   2020-02-15 (Sat, 15 Feb 2020)

  Changed paths:
    M qapi/block-core.json

  Log Message:
  -----------
  qapi/block-core.json: Use literal block for ascii art

The ascii-art graph in the BlockLatencyHistogramInfo documentation
doesn't render correctly, because the whitespace is collapsed.

Use the '|' format that emits a literal 'example' block so the graph
is displayed correctly.

Strictly the Texinfo generated is still wrong because each line
goes into its own @example environment, but it renders better
than what we had before.

Fixing this rendering is a necessary prerequisite for the upcoming rST
generator, which otherwise complains about the inconsistent
indentation in the ascii-art graph.

Signed-off-by: Peter Maydell <address@hidden>
Message-Id: <address@hidden>
Reviewed-by: Markus Armbruster <address@hidden>
[Commit message tweaked]
Signed-off-by: Markus Armbruster <address@hidden>


  Commit: f56275064e06974b5c03f37ccdb124adbc5baef6
      
https://github.com/qemu/qemu/commit/f56275064e06974b5c03f37ccdb124adbc5baef6
  Author: Peter Maydell <address@hidden>
  Date:   2020-02-15 (Sat, 15 Feb 2020)

  Changed paths:
    M qapi/block-core.json

  Log Message:
  -----------
  qapi: Fix incorrect "Not documented" claims in QMP documentation

Some qapi doc comments have forgotten the ':' after the
@argument, like this:

# @filename         Filename for the new image file
# @size             Size of the virtual disk in bytes

The result is that these are parsed as part of the body
text and appear as a run-on line:
  filename Filename for the new image file size Size of the virtual disk in 
bytes"
followed by
  filename: string
    Not documented
  size: int
    Not documented

in the 'Members' section.

Correct the formatting.

Signed-off-by: Peter Maydell <address@hidden>
Reviewed-by: Markus Armbruster <address@hidden>
Message-Id: <address@hidden>
[Commit message tweaked]
Signed-off-by: Markus Armbruster <address@hidden>


  Commit: 26ec4e53f2bf0a381189071f405b99a7e2627a49
      
https://github.com/qemu/qemu/commit/26ec4e53f2bf0a381189071f405b99a7e2627a49
  Author: Peter Maydell <address@hidden>
  Date:   2020-02-15 (Sat, 15 Feb 2020)

  Changed paths:
    M qapi/block-core.json
    M qapi/block.json
    M qapi/char.json
    M qapi/dump.json
    M qapi/introspect.json
    M qapi/job.json
    M qapi/machine-target.json
    M qapi/machine.json
    M qapi/migration.json
    M qapi/misc-target.json
    M qapi/misc.json
    M qapi/net.json
    M qapi/qdev.json
    M qapi/qom.json
    M qapi/rocker.json
    M qapi/run-state.json
    M qapi/sockets.json
    M qapi/trace.json
    M qapi/transaction.json
    M qapi/ui.json

  Log Message:
  -----------
  qapi: Fix indent level on doc comments in json files

The current doc generation doesn't care much about indentation levels,
but we would like to switch to an rST format, and rST does care about
indentation.

Make the doc comments more strongly consistent about indentation
for multiline constructs like:

@arg: description line 1
      description line 2

Returns: line one
         line 2

so that there is always exactly one space after the colon, and
subsequent lines align with the first.

This commit is a purely whitespace change, and it does not alter the
generated .texi files (because the texi generation code strips away
all the extra whitespace).  This does mean that we end up with some
over-length lines.

Note that when the documentation for an argument fits on a single
line like this:

@arg: one line only

then stray extra spaces after the ':' don't affect the rST output, so
I have not attempted to methodically fix them, though the preference
is a single space here too.

Signed-off-by: Peter Maydell <address@hidden>
Message-Id: <address@hidden>
Reviewed-by: Markus Armbruster <address@hidden>
[Commit message tweaked]
Signed-off-by: Markus Armbruster <address@hidden>


  Commit: dbb28bc8508ad967f84bb88dc7a2c86fe7d3c8fe
      
https://github.com/qemu/qemu/commit/dbb28bc8508ad967f84bb88dc7a2c86fe7d3c8fe
  Author: Peter Maydell <address@hidden>
  Date:   2020-02-15 (Sat, 15 Feb 2020)

  Changed paths:
    M qapi/block-core.json
    M qapi/migration.json

  Log Message:
  -----------
  qapi: Remove hardcoded tabs

There are some stray hardcoded tabs in some of our json files;
remove them.

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


  Commit: 43d7c2d06e1c60c60dca8792edb92116d1ec815c
      
https://github.com/qemu/qemu/commit/43d7c2d06e1c60c60dca8792edb92116d1ec815c
  Author: Peter Maydell <address@hidden>
  Date:   2020-02-15 (Sat, 15 Feb 2020)

  Changed paths:
    M qapi/ui.json

  Log Message:
  -----------
  qapi/ui.json: Put input-send-event body text in the right place

In the doc comment for input-send-event, there is a multi-line
chunk of text ("The @device...take precedence") which is intended
to be the main body text describing the event. However it has
been placed after the arguments and Returns: section, which
means that the parser actually thinks that this text is
part of the "Returns" section text.

Move the body text up to the top so that the parser correctly
classifies it as body.

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


  Commit: 449be9df521c87c5b7b12c5e66d006d4cba80aaa
      
https://github.com/qemu/qemu/commit/449be9df521c87c5b7b12c5e66d006d4cba80aaa
  Author: Peter Maydell <address@hidden>
  Date:   2020-02-15 (Sat, 15 Feb 2020)

  Changed paths:
    M qapi/ui.json

  Log Message:
  -----------
  qapi/ui.json: Avoid `...' Texinfo style quoting

Avoid Texinfo style quoting with `...', because we would like to
switch the doc comments to rST format, and rST treats it as a syntax
error. Use '...' instead, as we do in other doc comments. This looks
OK in Texinfo, and rST formats it as paired-quotation-marks.

Signed-off-by: Peter Maydell <address@hidden>
Reviewed-by: Markus Armbruster <address@hidden>
Message-Id: <address@hidden>
[Commit message tweaked]
Signed-off-by: Markus Armbruster <address@hidden>


  Commit: e050e426782ec4ae6bf84e5ec75ca502187f69cb
      
https://github.com/qemu/qemu/commit/e050e426782ec4ae6bf84e5ec75ca502187f69cb
  Author: Peter Maydell <address@hidden>
  Date:   2020-02-15 (Sat, 15 Feb 2020)

  Changed paths:
    M qapi/block-core.json
    M qapi/block.json
    M qapi/misc.json
    M qapi/tpm.json
    M qapi/ui.json

  Log Message:
  -----------
  qapi: Use explicit bulleted lists

A JSON block comment like this:
     Returns: nothing on success
              If @node is not a valid block device, DeviceNotFound
              If @name is not found, GenericError with an explanation

renders like this:

     Returns: nothing on success If node is not a valid block device,
     DeviceNotFound If name is not found, GenericError with an explanation

because whitespace is not significant.

Use an actual bulleted list, so that the formatting is correct.

Signed-off-by: Peter Maydell <address@hidden>
Message-Id: <address@hidden>
Message-Id: <address@hidden>
Message-Id: <address@hidden>
[Three commits squashed into one]
Reviewed-by: Markus Armbruster <address@hidden>
Signed-off-by: Markus Armbruster <address@hidden>


  Commit: 100cc4fe0f0827f8da1a5c05f9c65e2aaa40e03d
      
https://github.com/qemu/qemu/commit/100cc4fe0f0827f8da1a5c05f9c65e2aaa40e03d
  Author: Peter Maydell <address@hidden>
  Date:   2020-02-15 (Sat, 15 Feb 2020)

  Changed paths:
    M qapi/block-core.json
    M qapi/char.json
    M qapi/trace.json
    M qapi/ui.json

  Log Message:
  -----------
  qapi: Add blank lines before bulleted lists

We would like to switch the doc comments to rST format. rST
insists on a blank line before and after a bulleted list, but our
Texinfo doc generator did not. Add some extra blank lines in the doc
comments so they're acceptable rST input.

Signed-off-by: Peter Maydell <address@hidden>
Reviewed-by: Philippe Mathieu-Daudé <address@hidden>
Message-Id: <address@hidden>
Reviewed-by: Markus Armbruster <address@hidden>
[Commit message tweaked]
Signed-off-by: Markus Armbruster <address@hidden>


  Commit: a660eed482063bc3bdf0416090c67a91743b2c42
      
https://github.com/qemu/qemu/commit/a660eed482063bc3bdf0416090c67a91743b2c42
  Author: Peter Maydell <address@hidden>
  Date:   2020-02-15 (Sat, 15 Feb 2020)

  Changed paths:
    M qapi/migration.json

  Log Message:
  -----------
  qapi/migration.json: Replace _this_ with *this*

The MigrationInfo::setup-time documentation is the only place where we
use _this_ inline markup for emphasis, commonly rendered in italics.
We would like to switch the doc comments to rST format, but rST
doesn't recognize that markup and emits literal underscores.

Switch to *this* instead.  Changes markup to strong emphasis with
Texinfo, commonly rendered as bold.  With rST, it will go right back
to emphasis / italics.

rST also uses **this** for strong (commonly rendered bold) where
Texinfo uses *this*. We have one place in the doc comments
which uses strong/bold markup, in qapi/introspect.json:
    Note: the QAPI schema is also used to help define *internal*

When we switch to rST that will be rendered as emphasis / italics.
Markus (who wrote that) thinks that using emphasis / italics
there is an improvement, so we leave that markup alone.

Signed-off-by: Peter Maydell <address@hidden>
Reviewed-by: Markus Armbruster <address@hidden>
Message-Id: <address@hidden>
Reviewed-by: Philippe Mathieu-Daudé <address@hidden>
[Commit message tweaked]
Signed-off-by: Markus Armbruster <address@hidden>


  Commit: bb5ccf225e81d2801c03e63d16c371f0617270e8
      
https://github.com/qemu/qemu/commit/bb5ccf225e81d2801c03e63d16c371f0617270e8
  Author: Peter Maydell <address@hidden>
  Date:   2020-02-15 (Sat, 15 Feb 2020)

  Changed paths:
    M qapi/machine.json
    M qapi/net.json
    M qapi/ui.json

  Log Message:
  -----------
  qapi: Delete all the "foo: dropped in n.n" notes

A handful of QAPI doc comments include lines like
"ppcemb: dropped in 3.1". The doc comment parser will just
put these into whatever the preceding section was; sometimes
that's "Notes", and sometimes it's some random other section,
as with "NetClientDriver" where the "'dump': dropped in 2.12"
line ends up in the "Since:" section.

This tends to render wrongly, more so in the upcoming rST
generator, but sometimes even in the Texinfo, as in the case
of QKeyCode:
   ac_bookmarks
       since 2.10 altgr, altgr_r: dropped in 2.10

Since commit 3264ffced3 (v4.2.0), we have a better place to tell
users about deprecated and deleted functionality --
qemu-deprecated.texi.  These "dropped in" remarks all predate it, and
other feature drops of that vintage are not documented anywhere, so
moving these to qemu-deprecated.texi makes little sense.  Drop them
instead.

Signed-off-by: Peter Maydell <address@hidden>
Message-Id: <address@hidden>
Reviewed-by: Markus Armbruster <address@hidden>
[Commit message tweaked]
Signed-off-by: Markus Armbruster <address@hidden>


  Commit: 9ced5c7c20cb16dff0c2fa3242c3ee96b68cec2a
      
https://github.com/qemu/qemu/commit/9ced5c7c20cb16dff0c2fa3242c3ee96b68cec2a
  Author: Peter Maydell <address@hidden>
  Date:   2020-02-16 (Sun, 16 Feb 2020)

  Changed paths:
    M Makefile
    M configure
    M docs/conf.py
    M qapi/block-core.json
    M qapi/block.json
    M qapi/char.json
    M qapi/dump.json
    M qapi/introspect.json
    M qapi/job.json
    M qapi/machine-target.json
    M qapi/machine.json
    M qapi/migration.json
    M qapi/misc-target.json
    M qapi/misc.json
    M qapi/net.json
    M qapi/qdev.json
    M qapi/qom.json
    M qapi/rocker.json
    M qapi/run-state.json
    M qapi/sockets.json
    M qapi/tpm.json
    M qapi/trace.json
    M qapi/transaction.json
    M qapi/ui.json
    M qga/qapi-schema.json

  Log Message:
  -----------
  Merge remote-tracking branch 'remotes/armbru/tags/pull-qapi-2020-02-15' into 
staging

QAPI patches for 2020-02-15

# gpg: Signature made Sat 15 Feb 2020 10:44:28 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-2020-02-15:
  qapi: Delete all the "foo: dropped in n.n" notes
  qapi/migration.json: Replace _this_ with *this*
  qapi: Add blank lines before bulleted lists
  qapi: Use explicit bulleted lists
  qapi/ui.json: Avoid `...' Texinfo style quoting
  qapi/ui.json: Put input-send-event body text in the right place
  qapi: Remove hardcoded tabs
  qapi: Fix indent level on doc comments in json files
  qapi: Fix incorrect "Not documented" claims in QMP documentation
  qapi/block-core.json: Use literal block for ascii art
  qga/qapi-schema.json: minor format fixups for rST
  qga/qapi-schema.json: Fix indent level on doc comments
  qga/qapi-schema.json: Fix missing '-' in GuestDiskBusType doc comment
  Makefile: Fix typo in dependency list for interop manpages
  configure: Check that sphinx-build is using Python 3
  configure: Pick sphinx-build-3 when available
  configure: Allow user to specify sphinx-build binary
  qapi: Expand documentation for LostTickPolicy

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


Compare: https://github.com/qemu/qemu/compare/971b2a1e5b1a...9ced5c7c20cb