On Fri, Mar 4, 2022 at 7:30 AM Markus Armbruster <arm...@redhat.com> wrote: > > Eugenio Perez Martin <epere...@redhat.com> writes: > > > Yes, that's right. I expressed my point poorly actually, I'll go the > > reverse. > > > > qapi-gen.py forces me to write a comment in the doc: > > qapi/block-core.json:2971: feature 'unstable' lacks documentation > > > > When I add the documentation line, it's enough to add @unstable. But > > there is no way to tell if this tag is because the whole struct is > > unstable or if it's because individual members are unstable unless the > > reader either checks the tag or the struct code. > > > > I was mostly worried about doc generators, I would not like to make > > NetdevVhostVDPAOptions unstable at this point. But I see that there is > > no problem with that. > > > > Thanks! > > Yes, the doc generator insists on features being documented, and it > doesn't provide for documenting them next to members, only top-level. > The common solution is to phrase the comment like we do in > BlockdevOptionsFile: > > # @unstable: Member x-check-cache-dropped is meant for debugging. > > If there were multiple members so flagged, we'd enumerate them all. > > The generator doesn't check you do this right. The existing check > guards against *forgetting* to do it, not against doing it wrong. > > More questions? >
Got it, it matches my impression. Thank you very much!
