linux-kernel - Re: [PATCH] kernel-doc: better handle '::' sequences

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20210325221437.GA1719932@casper.infradead.org>
Date:   Thu, 25 Mar 2021 22:14:37 +0000
From:   Matthew Wilcox <willy@...radead.org>
To:     Jonathan Corbet <corbet@....net>
Cc:     Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
        Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Rob Herring <robh@...nel.org>, linux-kernel@...r.kernel.org
Subject: Re: [PATCH] kernel-doc: better handle '::' sequences

On Thu, Mar 25, 2021 at 03:04:00PM -0600, Jonathan Corbet wrote:
> Matthew Wilcox <willy@...radead.org> writes:
> > 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.
> 
> Yeah, the thing is that, as long as we're documenting code with
> something other than RST, we *do* have two formats, and they interact
> with each other in surprising and unwelcome ways.
> 
> I don't really see a fix, though.  Even if we come up with the Perfect
> New Format™, I don't want to be the one trying to push through the
> patches changing tens of thousands of kerneldoc comments over...

I can't argue with either of your points.

The rust code is alredy coming though ...

rust/kernel/buffer.rs:/// A pre-allocated buffer that implements [`core::fmt::Write`].

so now we have three formats.  Markdown and RST are _very_ similar, but
not identical [1].  Oh, and even better we now have three distinct tools --
kerneldoc, rustdoc and sphinx.  Have the rust people reached out to you
about integrating the various docs?

[1] https://en.wikipedia.org/wiki/Lightweight_markup_language#Comparison_of_lightweight_markup_language_syntax