On Fri, Jun 18, 2021 at 10:26:59AM +0200, Paolo Bonzini wrote:
> On 18/06/21 09:02, Greg KH wrote:
> > > + struct kvm_stats_desc {
> > > + __u32 flags;
> > > + __s16 exponent;
> > > + __u16 size;
> > > + __u32 offset;
> > > + __u32 unused;
> > > + char name[];
> > > + };
> > As I mention in another patch, this should be sucked in directly from
> > the .h file in kerneldoc format, so that everything stays in sync. I
> > bet almost this whole file can be put into the .h file, look at how drm
> > and v4l2 does this in a way that you only have to write the above one
> > time, not try to keep it in sync in two different places.
>
> V4L's userspace-api/media/v4l is absurdly good and I'd say it's by far the
> best documentation of any Linux subsystem, but it's all handwritten just
> like in KVM. In fact, grepping for kernel-doc directives in Documentation/
> gives no hits for the V4L uAPI documentation.
>
> DRM has great kernel documentation, but quality-wise the KVM userland
> documentation is on a completely different level compared to DRM; just
> compare https://www.kernel.org/doc/html/latest/virt/kvm/api.html to
> https://www.kernel.org/doc/html/latest/gpu/drm-uapi.html. The latter is not
> about how to use the DRM interfaces from userspace, it's about how to
> implement the userspace interfaces. It is full of kernel struct definitions
> that should have no place in a uAPI manual, and does not include
> documentation for almost anything in include/uapi/drm/drm.h
Ok, it's your maintenance burden, not mine, I was just suggesting a way
to make it easier :)
I'll not complain about this anymore...
thanks,
greg k-h
