Em Fri, 13 Oct 2017 15:38:11 +0300 Laurent Pinchart <laurent.pinch...@ideasonboard.com> escreveu:
> Hi Mauro, > > Thank you for the patch. > > On Thursday, 28 September 2017 00:46:51 EEST Mauro Carvalho Chehab wrote: > > Currently, there's no way to document #define foo <value> > > with kernel-doc. So, convert it to an enum, and document. > > The documentation seems fine to me (except for one comment below). However, > converting macros to an enum just to work around a defect of the > documentation > system doesn't seem like a good idea to me. I'd rather find a way to document > macros. I agree that this limitation should be fixed. Yet, in this specific case where we have an "array" of defines, all associated to the same field (even being a bitmask), and assuming that we would add a way for kernel-doc to parse this kind of defines (not sure how easy/doable would be), then, in order to respect the way kernel-doc markup is, the documentation for those macros would be: /** * define: Just log the ioctl name + error code */ #define V4L2_DEV_DEBUG_IOCTL 0x01 /** * define: Log the ioctl name arguments + error code */ #define V4L2_DEV_DEBUG_IOCTL_ARG 0x02 /** * define: Log the file operations open, release, mmap and get_unmapped_area */ #define V4L2_DEV_DEBUG_FOP 0x04 /** * define: Log the read and write file operations and the VIDIOC_(D)QBUF ioctls */ #define V4L2_DEV_DEBUG_STREAMING 0x08 IMHO, this is a way easier to read/understand by humans, and a way more coincise: /** * enum v4l2_debug_flags - Device debug flags to be used with the video * device debug attribute * * @V4L2_DEV_DEBUG_IOCTL: Just log the ioctl name + error code. * @V4L2_DEV_DEBUG_IOCTL_ARG: Log the ioctl name arguments + error code. * @V4L2_DEV_DEBUG_FOP: Log the file operations and open, release, * mmap and get_unmapped_area syscalls. * @V4L2_DEV_DEBUG_STREAMING: Log the read and write syscalls and * :c:ref:`VIDIOC_[Q|DQ]BUFF <VIDIOC_QBUF>` ioctls. */ It also underlines the aspect that those names are grouped altogether. So, IMHO, the main reason to place them inside an enum and document as such is that it looks a way better for humans to read. Thanks, Mauro -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
