Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
Date:   Thu, 25 Mar 2021 19:14:35 +0000
From:   Matthew Wilcox <willy@infradead.org>
To:     Jonathan Corbet <corbet@lwn.net>
Cc:     Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
        Linux Doc Mailing List <linux-doc@vger.kernel.org>,
        Rob Herring <robh@kernel.org>, linux-kernel@vger.kernel.org
Subject: Re: [PATCH] kernel-doc: better handle '::' sequences
Message-ID: <20210325191435.GZ1719932@casper.infradead.org>
References: <20210325184615.08526aed@coco.lan>
 <2cf44cf1fa42588632735d4fbc8e84304bdc235f.1616696051.git.mchehab+huawei@kernel.org>
 <87tuozyslu.fsf@meer.lwn.net>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <87tuozyslu.fsf@meer.lwn.net>
Precedence: bulk

On Thu, Mar 25, 2021 at 12:51:25PM -0600, Jonathan Corbet wrote:
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> > Right now, if one of the following headers end with a '::', the
> > kernel-doc script will do the wrong thing:
> >
> > 	description|context|returns?|notes?|examples?
> >
> > The real issue is with examples, as people could try to write
> > something like:
> >
> > 	example::
> >
> > 		/* Some C code */
> >
> > and this won't be properly evaluated. So, improve the regex
> > to not catch '\w+::' regex for the above identifiers.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> >  scripts/kernel-doc | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> Ah....wouldn't it be nice if kerneldoc comments had just been RST from
> the beginning?  I don't think we're fixing that at this point, though,
> so this makes sense; applied.

Well ...

If somebody wants to write a new tool (*) that extracts documentation
written in a different format, I think that could be done.  Because the
hard part of writing documentation is getting the person who knows the
code to get everything that's in their brain into words, not really
the formatting.

If somebody did want to write such a tool, I think we'd also want a
tool that turns the existing kernel-doc into the new format, because
maintaining two function-doc formats would be awful.

https://blog.golang.org/godoc would be my preferred format ... the less
information repeated from the actual function, the better.  But if
we're actually going to have rust in the kernel, perhaps rustdoc is
better.  https://doc.rust-lang.org/beta/rust-by-example/meta/doc.html

(*) because nobody actually likes kernel-doc.pl, right?