Dave Chinner <david@xxxxxxxxxxxxx> writes: One little point among all the more substantial stuff: >> -/* >> - * Types of block ranges for iomap mappings: >> +/** >> + * DOC: iomap block ranges types > > I seriously dislike this "DOC:" keyword appearing everywhere. > We've already got a "this is a comment for documentation" annotation > in the "/**" comment prefix, having to add "DOC:" is entirely > redudant and unnecessary noise. DOC: actually isn't redundant, it causes the kernel-doc directive to pull that text into the rendered documentation. This document shows both the advantages and disadvantages of that mechanism, IMO. It allows the documentation to be kept with the code, where optimistic people think it is more likely to be updated. But it also scatters the material to the detriment of readers of the plain-text documentation. The rendered version of iomap.rst is rather more complete and comprehensible than the RST file itself. Thanks, jon
