Return-Path: <linux-kernel-owner@vger.kernel.org>
Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand
        id S1753245AbdLHVWp (ORCPT <rfc822;w@1wt.eu>);
        Fri, 8 Dec 2017 16:22:45 -0500
Received: from smtprelay0042.hostedemail.com ([216.40.44.42]:55404 "EHLO
        smtprelay.hostedemail.com" rhost-flags-OK-OK-OK-FAIL)
        by vger.kernel.org with ESMTP id S1752352AbdLHVWl (ORCPT
        <rfc822;linux-kernel@vger.kernel.org>);
        Fri, 8 Dec 2017 16:22:41 -0500
X-Session-Marker: 6A6F6540706572636865732E636F6D
X-Spam-Summary: 2,0,0,,d41d8cd98f00b204,joe@perches.com,:::::::::::::,RULES_HIT:41:355:379:541:599:960:973:988:989:1260:1277:1311:1313:1314:1345:1359:1373:1437:1515:1516:1518:1534:1541:1593:1594:1711:1730:1747:1777:1792:2194:2199:2393:2559:2562:2828:2895:2915:3138:3139:3140:3141:3142:3353:3622:3865:3866:3867:3868:3870:3871:3872:3874:4321:5007:6119:6120:7903:9108:10004:10400:10848:11232:11658:11914:12043:12740:12760:12895:13069:13161:13229:13311:13357:13439:14096:14097:14181:14659:14721:21063:21080:21627:30003:30012:30054:30070:30091,0,RBL:none,CacheIP:none,Bayesian:0.5,0.5,0.5,Netcheck:none,DomainCache:0,MSF:not bulk,SPF:,MSBL:0,DNSBL:none,Custom_rules:0:0:0,LFtime:1,LUA_SUMMARY:none
X-HE-Tag: jelly90_171f585d53113
X-Filterd-Recvd-Size: 2527
Message-ID: <1512768157.1845.30.camel@perches.com>
Subject: Re: [PATCH] doc: convert printk-formats.txt to rst
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>
Date: Fri, 08 Dec 2017 13:22:37 -0800
In-Reply-To: <CAGXu5j+q3vXeM-KUwGAY49--o-_jw8i69Lff1M6R67E4qjkCRw@mail.gmail.com>
References: <1512524729-16051-1-git-send-email-me@tobin.cc>
         <CAGXu5j+ACnv3qUFF8hfr_+5Of=8i1gcQ596hNLvw4g9RbpViyg@mail.gmail.com>
         <20171207234402.GT2191@eros>
         <CAGXu5j+fFu7_quVm4+q3Npf_iWN5xjy9GzuYCDcxFW9RSyVkPQ@mail.gmail.com>
         <20171208004627.GW2191@eros>
         <CAGXu5j+q3vXeM-KUwGAY49--o-_jw8i69Lff1M6R67E4qjkCRw@mail.gmail.com>
Content-Type: text/plain; charset="ISO-8859-1"
X-Mailer: Evolution 3.26.1-1 
Mime-Version: 1.0
Content-Transfer-Encoding: 7bit
Sender: linux-kernel-owner@vger.kernel.org
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org
Content-Length: 1297
Lines: 34

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.