On Sun, 01 Jan 2017, Jonathan Cameron <jic23@xxxxxxxxxx> wrote: > Hi All, > > I have very little idea how the internals of the kernel-doc processing > code work, but was wondering if it would be possible to suppress warnings > of the type: > > ./include/linux/iio/buffer.h:142: warning: Excess struct/union/enum/typedef member 'ref' description in 'iio_buffer' > > when the member is there but has been marked private. That's not marked private, and I don't see the error. Is this a made up example? > I don't really want to end up deliberately having different formatting > for documentation of internal structure elements and public API ones. > > Obviously I can just ignore the warnings, but they do swamp any real issues > once you start dealing with large structures. I presume the idea behind "private" is that you only document the public interface using kernel-doc. That's how the examples in scripts/kernel-doc look like anyway. For your buffer.h example, I think I'd go with either a) switching to in-line documentation of the members, and then using normal comments instead of /** for the private members, or b) documenting each private member as private in the documentation comments, instead of using the special /* private: */ comment (and actually they already seem to have the scope documented). Implementation wise, kernel-doc uses regexps to ignore the members after the "private" designation, but then it parsers the comments separately. So it doesn't see the private members, but it will see the comments. After that, the documentation of the private members are indistinguishable from documentation of non-existing members for kernel-doc. Fixing this doesn't look like a very pleasant task, and judging by the kernel-doc documentation and implementation, it works as originally intended. It's not a bug, it's a feature. ;) BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
