Re: [PATCH v3 14/14] vdpa: Add x-svq to NetdevVhostVDPAOptions

[Eugenio Perez Martin]

On Fri, Mar 4, 2022 at 7:30 AM Markus Armbruster <armbru@redhat.com> wrote:
>
> Eugenio Perez Martin <eperezma@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!