Return-Path: <linux-kernel-owner@vger.kernel.org>
Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand
        id S1753566AbdLIB1o (ORCPT <rfc822;w@1wt.eu>);
        Fri, 8 Dec 2017 20:27:44 -0500
Received: from out3-smtp.messagingengine.com ([66.111.4.27]:55163 "EHLO
        out3-smtp.messagingengine.com" rhost-flags-OK-OK-OK-OK)
        by vger.kernel.org with ESMTP id S1752050AbdLIB1l (ORCPT
        <rfc822;linux-kernel@vger.kernel.org>);
        Fri, 8 Dec 2017 20:27:41 -0500
X-ME-Sender: <xms:DTwrWldCQl4LJSSJExqy7ExIRaLs3sLT1ZboZdZdwiC_dQe1Bc8seA>
Date: Sat, 9 Dec 2017 12:27:36 +1100
From: "Tobin C. Harding" <me@tobin.cc>
To: Joe Perches <joe@perches.com>
Cc: Kees Cook <keescook@chromium.org>, Jonathan Corbet <corbet@lwn.net>,
        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
Message-ID: <20171209012736.GC2191@eros>
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>
 <1512768157.1845.30.camel@perches.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <1512768157.1845.30.camel@perches.com>
X-Mailer: Mutt 1.5.24 (2015-08-30)
User-Agent: Mutt/1.5.24 (2015-08-30)
Sender: linux-kernel-owner@vger.kernel.org
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org
Content-Length: 1744
Lines: 44

On Fri, Dec 08, 2017 at 01:22:37PM -0800, Joe Perches wrote:
> 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.

Ok, thanks. Will re-spin without kernel-doc-ification in vsprintf.c

> 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.

This sounds interesting to work no. At first glance I have no idea how
one would go about this. Some form of static analysis would be a good
place to start, right? I'd like to allocate some cycles to this, any
pointers most appreciated.

thanks,
Tobin.