linux-kernel - Re: [PATCH] doc: convert printk-formats.txt to rst

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: <1512768157.1845.30.camel@perches.com>
Date:   Fri, 08 Dec 2017 13:22:37 -0800
From:   Joe Perches <joe@...ches.com>
To:     Kees Cook <keescook@...omium.org>,
        "Tobin C. Harding" <me@...in.cc>, Jonathan Corbet <corbet@....net>
Cc:     Randy Dunlap <rdunlap@...radead.org>,
        Andrew Murray <amurray@...-data.co.uk>,
        linux-doc@...r.kernel.org, LKML <linux-kernel@...r.kernel.org>
Subject: Re: [PATCH] doc: convert printk-formats.txt to rst

On Fri, 2017-12-08 at 13:06 -0800, Kees Cook wrote:
> Well ... my sense is that lib/vsprintf.c should remain the canonical
> documentation.

I agree.

> Anyone working on the code has the docs all together in
> one file. If it helps the .rst file to reformat the comments into
> kernel-doc, that's fine, but it shouldn't reduce the detail that is
> present, IMO. Now, expanding on it in printk-formats.rst is certainly
> a great idea, but I don't think it should come at the expense of
> someone just reading through vsprintf.c. That said, I can certainly
> see that redundancy is annoying, and it's possible for
> printk-formats.rst and vsprintf.c get get out of sync, but that
> doesn't seem to be a new problem.

Nor has it been a real problem in practice.

There is a comment in vsprintf.c that tells people
to update the doc.

 * ** Please update also Documentation/printk-formats.txt when making changes **
> 
> I'd be curious to see what Jon or Joe think about this.
> 
> (Perhaps the best first step would be to leave vsprintf.c as-is
> without kernel-doc-ification?)

I think adding kernel-doc to vsprintf.c is unnecessary.

Outside of the documentation, what could be useful is for
someone to add a tool to verify %p<foo> extension to
the typeof address actually passed as an argument.