Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
Date:   Mon, 30 Mar 2020 16:32:55 -0600
From:   Jonathan Corbet <corbet@lwn.net>
To:     Peter Lister <peter@bikeshed.quignogs.org.uk>
Cc:     Jani Nikula <jani.nikula@linux.intel.com>,
        Matthew Wilcox <willy@infradead.org>,
        linux-kernel@vger.kernel.org,
        Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
        "Rafael J. Wysocki" <rafael@kernel.org>, linux-doc@vger.kernel.org
Subject: Re: [PATCH v3 0/1] Compactly make code examples into literal blocks
Message-ID: <20200330163255.4322e763@lwn.net>
In-Reply-To: <7d7f4cbb-e8e8-411d-62f4-7a32a2ac8d8a@bikeshed.quignogs.org.uk>
References: <20200326192947.GM22483@bombadil.infradead.org>
        <20200326195156.11858-1-peter@bikeshed.quignogs.org.uk>
        <87imiqghop.fsf@intel.com>
        <20200327104126.667b5d5b@lwn.net>
        <7d7f4cbb-e8e8-411d-62f4-7a32a2ac8d8a@bikeshed.quignogs.org.uk>
Organization: LWN.net
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 8bit
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

On Mon, 30 Mar 2020 23:29:24 +0100
Peter Lister <peter@bikeshed.quignogs.org.uk> wrote:

One quick thing caught my eye...

> One head-on approachis to literalise *all* kerneldoc comments for 
> functions and structures. The kerneldoc keywords then serve only to 
> generate links; the ReST output is minimal but guaranteed validand 
> warning free. Would any readers of API docs be inconvenienced? The 
> target readership are presumably programmers, and the searchability of 
> the sphinx RTD is more useful to me than the formatting.

The ability to put formatting directive into kerneldoc comments was one of
the driving forces that pushed the RST switch in the first place.  There
are subsystems that make use of this capability and would not be pleased
to see it go away.

jon