linux-kernel - Re: [RFC] scripts: kernel-doc: Major kernel-doc rework

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] [day] [month] [year] [list]

Message-ID: <87k0do8jhq.fsf@intel.com>
Date:   Mon, 21 Feb 2022 14:57:53 +0200
From:   Jani Nikula <jani.nikula@...ux.intel.com>
To:     Matthew Wilcox <willy@...radead.org>,
        Jonathan Corbet <corbet@....net>
Cc:     Tomasz Warniełło <tomasz.warniello@...il.com>,
        linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: [RFC] scripts: kernel-doc: Major kernel-doc rework

On Fri, 18 Feb 2022, Matthew Wilcox <willy@...radead.org> wrote:
> On Thu, Feb 17, 2022 at 10:04:23AM -0700, Jonathan Corbet wrote:
>> *I* prefer Python, and the Sphinx side of things is necessarily in
>> Python, so I'd be happy to see kernel-doc move over.  That said, others
>> certainly disagree.
>> 
>> Markus's work was here:
>> 
>>   https://lore.kernel.org/lkml/1485287564-24205-1-git-send-email-markus.heiser@darmarit.de/
>> 
>> At the time, we were just trying to get the RST transition done, and
>> swapping out the kernel-doc script seemed like a major distraction that
>> we didn't need, so this never got looked at as seriously as I would have
>> liked.
>
> Personally, I'd like to see us switch over to
> https://github.com/jnikula/hawkmoth
>
> but I don't have time to work on the rough edges.

Basically Hawkmoth is my idea how C documentation comments should be
incorporated to Sphinx *if* there is no legacy to care about. In that
sense, I never wrote it with the kernel documentation in mind, on the
contrary it's a hobby project where I can just not think about the
kernel at all. ;)

With that in mind, I'd really like to hear what the rough edges are that
you see. Or are they kernel specific? Preferrably as issues on the
project page if you don't mind.

> I really hate the kernel-doc style; I think it makes us write very
> stilted documentation, full of parameter descriptions like:
>
>  function() - Do the thing to a page.
>  @page: The page.
>
> which really serves nobody.  Being able to write:
>
>  function() - Do the thing to @page
>
> is easier to both write and read.

I tend to agree. Though Hawkmoth does not take a stand here, basically
the assumption is that the documentation comments are pure rst. And that
was one of the goals, no parsing of the comments beyond removing the C
comment markers. It's up to the users or projects to dictate what the
comments should look like. There's some plugin support for users to add
their own filters, e.g. there could be kernel-doc format support via
that.

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Graphics Center