From: Joe Perches <joe@perches.com>
To: Kees Cook <keescook@chromium.org>,
"Tobin C. Harding" <me@tobin.cc>,
Jonathan Corbet <corbet@lwn.net>
Cc: Randy Dunlap <rdunlap@infradead.org>,
Andrew Murray <amurray@mpc-data.co.uk>,
linux-doc@vger.kernel.org, LKML <linux-kernel@vger.kernel.org>
Subject: Re: [PATCH] doc: convert printk-formats.txt to rst
Date: Fri, 08 Dec 2017 13:22:37 -0800 [thread overview]
Message-ID: <1512768157.1845.30.camel@perches.com> (raw)
In-Reply-To: <CAGXu5j+q3vXeM-KUwGAY49--o-_jw8i69Lff1M6R67E4qjkCRw@mail.gmail.com>
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.
next prev parent reply other threads:[~2017-12-08 21:22 UTC|newest]
Thread overview: 25+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-12-06 1:45 [PATCH] doc: convert printk-formats.txt to rst Tobin C. Harding
2017-12-06 7:11 ` Markus Heiser
2017-12-06 7:35 ` Joe Perches
2017-12-06 17:55 ` Randy Dunlap
2017-12-06 18:18 ` Randy Dunlap
2017-12-06 21:16 ` Tobin C. Harding
2017-12-07 0:39 ` Randy Dunlap
2017-12-07 5:25 ` Tobin C. Harding
2017-12-06 22:11 ` Tobin C. Harding
2017-12-06 18:23 ` Jonathan Corbet
2017-12-06 21:30 ` Tobin C. Harding
2017-12-07 22:50 ` Kees Cook
2017-12-07 23:01 ` Jonathan Corbet
2017-12-07 23:50 ` Tobin C. Harding
2017-12-07 23:44 ` Tobin C. Harding
2017-12-08 0:19 ` Kees Cook
2017-12-08 0:46 ` Tobin C. Harding
2017-12-08 21:06 ` Kees Cook
2017-12-08 21:22 ` Joe Perches [this message]
2017-12-09 1:27 ` Tobin C. Harding
2017-12-09 2:18 ` Joe Perches
2017-12-09 6:33 ` Tobin C. Harding
2017-12-11 18:40 ` Laura Abbott
2017-12-09 11:48 ` Dan Carpenter
2017-12-11 0:51 ` Kees Cook
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1512768157.1845.30.camel@perches.com \
--to=joe@perches.com \
--cc=amurray@mpc-data.co.uk \
--cc=corbet@lwn.net \
--cc=keescook@chromium.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=me@tobin.cc \
--cc=rdunlap@infradead.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).