Re: [PATCH v4 2/2] Documentation: mtd: remove stale pxa3xx NAND controller documentation

[Boris Brezillon <boris.brezillon@bootlin.com>]

Hi Robert,

On Sun, 05 Aug 2018 21:06:48 +0200
Robert Jarzmik <robert.jarzmik@free.fr> wrote:

> Miquel Raynal <miquel.raynal@bootlin.com> writes:
> 
> > It is preferred to have the documentation about the drivers directly
> > embedded in the driver itself.  
> Could you tell me where this statement comes from ?
> 
> Because so far I've always been told the opposite.

I complained about that when I inadvertently discovered there was a doc
explaining how the marvell IP works in Documentation/mtd/nand/
(which happened after someone posted a patch series adding a new file
there). That's really something I'd expect to be described inside the
driver directly. I'm perfectly fine having framework documentation or
even SoC documentation placed in Documentation, but when it comes to
driver/IP documentation it's IMO better placed directly in the driver
source code, just because people usually don't look for driver-specific
doc in Documentation/.

A compromise would be to have everything documented in the driver
using overview doc comments [1], and then let sphynx parse this doc
header and generate the proper doc entry, but that's IMHO less important
to have such IP-specific information embedded in the kernel doc.

Regards,

Boris

[1]https://www.kernel.org/doc/html/v4.11/doc-guide/kernel-doc.html#overview-documentation-comments