On 2 January 2017 09:26:03 GMT+00:00, Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx> wrote: >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? Ah sorry, should have said. I am in process of tidying the docs up in that file. > >> 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). Makes sense if a little ugly! > >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. ;) Ah well such is life I guess. Thanks, Jonathan > > >BR, >Jani. -- Sent from my Android device with K-9 Mail. Please excuse my brevity. -- 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
