On 29.10.25 11:29, Markus Armbruster wrote:
Daniel P. Berrangé <[email protected]> writes:
On Sat, Oct 11, 2025 at 05:04:06PM +0300, Vladimir Sementsov-Ogievskiy wrote:
Hi all!
Let's bring the documentation in line with the requirements. And
do check these requirements in QAPI parser.
This implicitly assumes that the requirements are desirable.
This is a large number of patches, showing the requirements are widely
ignored today. When I look at the changes in the patches my overwhealming
reaction is that they are not beneficial, which in turn makes me believe
the requirements should be changed to match the reality of the code,
rather than the reverse.
A QAPI schema contains four distinct kinds of text:
1. Schema code
2. Example code in comments
3. Doc comments less example code, i.e. prose
4. Non-doc comments
This series touches all four.
I'm unsure about [1.]. What do you mean? The series touch only comments.
I now check:
git diff 37137ae582 HEAD | grep '^[+-][^#+-]'
where 37137ae582 is first commit "qapi: Add documentation format validation"
for me, and this grep finds nothing..
Assume [4.] is a tiny part.
"The requirements" refers to docs/devel/qapi-code-gen.rst section
Documentation comments / Documentation markup:
For legibility, wrap text paragraphs so every line is at most 70
characters long.
Separate sentences with two spaces.
I've explained why these rules make sense a number of times, and I'm
happy to explain again if needed.
Note this applies only to doc comments.
I've been enforcing it manually for prose. Whether it should be
enforced for example code is debatable. Let's focus on prose.
"Widely ignored" is not true, and I have numbers to back that up.
We have some 20,000 lines of doc comments in the main QAPI schema and
the QGA QAPI schema. Some 3,000 lines are examples. That leaves a bit
over 17,000 lines of prose in 48 files.
If I drop the changes to the other three kinds from Vladimir's series,
and add a few more prose changes he missed
Hmm it surprises me.. Does it mean that the check added in patch 01 misses
some violations?
, I get this diffstat:
24 files changed, 351 insertions(+), 332 deletions(-)
Compare with original diffstat:
33 files changed, 713 insertions(+), 704 deletions(-)
So obviously, touching up code examples makes the series twice more invasive.
I agree, to at least postpone examples changing. And the series show, that in
many
cases there are no obvious possibility to satisfy restrictions for examples.
Hmm, probably, we want another limit for examples? 90 characters? Anyway, not
in this
series.
--
Best regards,
Vladimir
