On Fri, Jun 18, 2021 at 10:26:59AM +0200, Paolo Bonzini wrote:

On 18/06/21 09:02, Greg KH wrote:

quoted

quoted

+	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