Re: [PATCH v2] Documentation: add initial iomap kdoc

[Jonathan Corbet <corbet@lwn.net>]

Dave Chinner <david@fromorbit.com> 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