riscv/qemu - qemu - Gitea: Git with a cup of tea

Commit Graph

Author	SHA1	Message	Date
Markus Armbruster	01bed0ff14	qapi: Refill doc comments to conform to conventions Sweep the entire documentation again. Last done in commit `209e64d9ed` (qapi: Refill doc comments to conform to current conventions). To check the generated documentation does not change, I compared the generated HTML before and after this commit with "wdiff -3". Finds no differences. Comparing with diff is not useful, as the reflown paragraphs are visible there. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240729065220.860163-1-armbru@redhat.com> [Straightforward conflict with commit `442110bc6f` resolved]	2 years ago
John Snow	14b48aaab9	qapi: convert "Example" sections without titles Use the no-option form of ".. qmp-example::" to convert any Examples that do not have any form of caption or explanation whatsoever. Note that in a few cases, example sections are split into two or more separate example blocks. This is only done stylistically to create a delineation between two or more logically independent examples. See commit-3: "docs/qapidoc: create qmp-example directive", for a detailed explanation of this custom directive syntax. See commit+3: "qapi: remove "Example" doc section" for a detailed explanation of why. Note: an empty "TODO" line was added to announce-self to keep the example from floating up into the body; this will be addressed more rigorously in the new qapidoc generator. Signed-off-by: John Snow <jsnow@redhat.com> Message-ID: <20240717021312.606116-7-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Markup fixed in one place] Signed-off-by: Markus Armbruster <armbru@redhat.com>	2 years ago
John Snow	d461c27973	qapi: convert "Note" sections to plain rST We do not need a dedicated section for notes. By eliminating a specially parsed section, these notes can be treated as normal rST paragraphs in the new QMP reference manual, and can be placed and styled much more flexibly. Convert all existing "Note" and "Notes" sections to pure rST. As part of the conversion, capitalize the first letter of each sentence and add trailing punctuation where appropriate to ensure notes look sensible and consistent in rendered HTML documentation. Markup is also re-aligned to the de-facto standard of 3 spaces for directives. Update docs/devel/qapi-code-gen.rst to reflect the new paradigm, and update the QAPI parser to prohibit "Note" sections while suggesting a new syntax. The exact formatting to use is a matter of taste, but a good candidate is simply: .. note:: lorem ipsum ... ... dolor sit amet ... ... consectetur adipiscing elit ... ... but there are other choices, too. The Sphinx readthedocs theme offers theming for the following forms (capitalization unimportant); all are adorned with a (!) symbol () in the title bar for rendered HTML docs. See https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/demo.html#admonitions for examples of each directive/admonition in use. These are rendered in orange: .. Attention:: ... .. Caution:: ... .. WARNING:: ... These are rendered in red: .. DANGER:: ... .. Error:: ... These are rendered in green: .. Hint:: ... .. Important:: ... .. Tip:: ... These are rendered in blue: .. Note:: ... .. admonition:: custom title admonition body text This patch uses ".. note::" almost everywhere, with just two "caution" directives. Several instances of "Notes:" have been converted to merely ".. note::", or multiple ".. note::" where appropriate. ".. admonition:: notes" is used in a few places where we had an ordered list of multiple notes that would not make sense as standalone/separate admonitions. Two "Note:" following "Example:" have been turned into ordinary paragraphs within the example. NOTE: Because qapidoc.py does not attempt to preserve source ordering of sections, the conversion of Notes from a "tagged section" to an "untagged section" means that rendering order for some notes may change as a result of this patch. The forthcoming qapidoc.py rewrite strictly preserves source ordering in the rendered documentation, so this issue will be rectified in the new generator. Signed-off-by: John Snow <jsnow@redhat.com> Acked-by: Stefan Hajnoczi <stefanha@redhat.com> [for block*.json] Message-ID: <20240626222128.406106-11-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Commit message clarified slightly, period added to one more note] Signed-off-by: Markus Armbruster <armbru@redhat.com>	2 years ago
Markus Armbruster	5305a4eeb8	qapi: Correct documentation indentation and whitespace Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240322140910.328840-12-armbru@redhat.com> [Add a previous patch's stray hunk]	2 years ago
Markus Armbruster	209e64d9ed	qapi: Refill doc comments to conform to current conventions For legibility, wrap text paragraphs so every line is at most 70 characters long. To check the generated documentation does not change, I compared the generated HTML before and after this commit with "wdiff -3". Finds no differences. Comparing with diff is not useful, as the refilled paragraphs are visible there. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240322140910.328840-11-armbru@redhat.com>	2 years ago
Markus Armbruster	53d5c36d8d	qapi: Delete useless "Returns" sections Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240227113921.236097-6-armbru@redhat.com>	2 years ago
Markus Armbruster	d23055b8db	qapi: Require descriptions and tagged sections to be indented By convention, we indent the second and subsequent lines of descriptions and tagged sections, except for examples. Turn this into a hard rule, and apply it to examples, too. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-11-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> [Straightforward conflicts in qapi/migration.json resolved]	2 years ago
Markus Armbruster	a57790f7d7	qapi/dump: Clean up documentation of DumpGuestMemoryCapability The type's doc comment describes its member, but it's not marked up as such. Easy enough to fix. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240205074709.3613229-12-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>	2 years ago
Stephen Brennan	e6549197f7	dump: Add command interface for kdump-raw formats The QMP dump API represents the dump format as an enumeration. Add three new enumerators, one for each supported kdump compression, each named "kdump-raw-*". For the HMP command line, rather than adding a new flag corresponding to each format, it seems more human-friendly to add a single flag "-R" to switch the kdump formats to "raw" mode. The choice of "-R" also correlates nicely to the "makedumpfile -R" option, which would serve to reassemble a flattened vmcore. Signed-off-by: Stephen Brennan <stephen.s.brennan@oracle.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> [ Marc-André: replace loff_t with off_t, indent fixes ] Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com> Message-Id: <20230918233233.1431858-4-stephen.s.brennan@oracle.com>	3 years ago
Markus Armbruster	a937b6aa73	qapi: Reformat doc comments to conform to current conventions Change # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed # do eiusmod tempor incididunt ut labore et dolore magna aliqua. to # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed # do eiusmod tempor incididunt ut labore et dolore magna aliqua. See recent commit "qapi: Relax doc string @name: description indentation rules" for rationale. Reflow paragraphs to 70 columns width, and consistently use two spaces to separate sentences. To check the generated documentation does not change, I compared the generated HTML before and after this commit with "wdiff -3". Finds no differences. Comparing with diff is not useful, as the reflown paragraphs are visible there. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20230428105429.1687850-18-armbru@redhat.com> Reviewed-by: Juan Quintela <quintela@redhat.com> Acked-by: Lukas Straub <lukasstraub2@web.de> [Straightforward conflicts in qapi/audio.json qapi/misc-target.json qapi/run-state.json resolved]	3 years ago
Markus Armbruster	22bd6e9c15	qapi/dump: Indent bulleted lists consistently Documentation of dump-guest-memory contains two bulleted lists. The first one is indented, the second one isn't. Delete the first one's indentation for a more consistent look. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20230428105429.1687850-9-armbru@redhat.com> Reviewed-by: Juan Quintela <quintela@redhat.com>	3 years ago
Victor Toso	612fb7cd54	qapi: fix example of query-dump-guest-memory-capability command Example output is missing closing curly brackets. Fix it. Problem was noticed when trying to load the example into python's json library. Signed-off-by: Victor Toso <victortoso@redhat.com> Message-Id: <20220901085840.22520-4-victortoso@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>	4 years ago
Andrea Bolognani	23e4645258	qapi: Drop unnecessary whitespace in comments The only instances that get changed are those in which the additional whitespace was not (or couldn't possibly be) used for alignment purposes. Signed-off-by: Andrea Bolognani <abologna@redhat.com> Message-Id: <20220503073737.84223-7-abologna@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>	4 years ago
Victor Toso	4375cf9868	qapi: fix example of dump-guest-memory Example output lacks mandatory member @paging. Provide it. Signed-off-by: Victor Toso <victortoso@redhat.com> Reviewed-by: John Snow <jsnow@redhat.com> Message-Id: <20220328140604.41484-15-victortoso@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>	4 years ago
Victor Toso	077a5b1ec3	qapi: fix example of DUMP_COMPLETED event Example output lacks mandatory member @timestamp. Provide it. Example output is not properly formatted. Fixing it by: - Adding '<-' to signalize it is receiving the data; - Adding extra spaces around members @result, @total and @completed Signed-off-by: Victor Toso <victortoso@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: John Snow <jsnow@redhat.com> Message-Id: <20220328140604.41484-6-victortoso@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>	4 years ago
Andrea Bolognani	f7160f3218	schemas: Add vim modeline The various schemas included in QEMU use a JSON-based format which is, however, strictly speaking not valid JSON. As a consequence, when vim tries to apply syntax highlight rules for JSON (as guessed from the file name), the result is an unreadable mess which mostly consist of red markers pointing out supposed errors in, well, pretty much everything. Using Python syntax highlighting produces much better results, and in fact these files already start with specially-formatted comments that instruct Emacs to process them as if they were Python files. This commit adds the equivalent special comments for vim. Signed-off-by: Andrea Bolognani <abologna@redhat.com> Message-Id: <20200729185024.121766-1-abologna@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Reviewed-by: John Snow <jsnow@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>	6 years ago
Peter Maydell	26ec4e53f2	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 <peter.maydell@linaro.org> Message-Id: <20200213175647.17628-10-peter.maydell@linaro.org> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Commit message tweaked] Signed-off-by: Markus Armbruster <armbru@redhat.com>	6 years ago
Markus Armbruster	d06b747bd5	qapi: Split dump.json off misc.json Move commands dump-guest-memory, query-dump, query-dump-guest-memory-capability with their types from misc.json to new dump.json. Add dump.json to MAINTAINERS section "Dump". Cc: Marc-André Lureau <marcandre.lureau@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20190619201050.19040-15-armbru@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>	7 years ago

18 Commits (4aef8b63e48ce459870c5ed78e86c0eaa331edac)