From patchwork Wed Jul 20 22:48:18 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 72519 Delivered-To: patch@linaro.org Received: by 10.140.29.52 with SMTP id a49csp121287qga; Wed, 20 Jul 2016 15:48:26 -0700 (PDT) X-Received: by 10.98.111.133 with SMTP id k127mr1092351pfc.90.1469054906338; Wed, 20 Jul 2016 15:48:26 -0700 (PDT) Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id m6si5733229pfi.52.2016.07.20.15.48.26; Wed, 20 Jul 2016 15:48:26 -0700 (PDT) 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; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932267AbcGTWsX (ORCPT + 29 others); Wed, 20 Jul 2016 18:48:23 -0400 Received: from tex.lwn.net ([70.33.254.29]:45821 "EHLO vena.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S932242AbcGTWsU convert rfc822-to-8bit (ORCPT ); Wed, 20 Jul 2016 18:48:20 -0400 Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by vena.lwn.net (Postfix) with ESMTP id 712B4154003E; Wed, 20 Jul 2016 16:48:19 -0600 (MDT) Date: Wed, 20 Jul 2016 16:48:18 -0600 From: Jonathan Corbet To: Daniel Vetter Cc: LKML , Jani Nikula , linux-doc@vger.kernel.org, Daniel Vetter Subject: Re: [PATCH] docs: Remove kernel-doc-nano-HOWTO.txt Message-ID: <20160720164818.2b1b044c@lwn.net> In-Reply-To: <1469010064-8604-1-git-send-email-daniel.vetter@ffwll.ch> References: <1469010064-8604-1-git-send-email-daniel.vetter@ffwll.ch> Organization: LWN.net X-Mailer: Claws Mail 3.13.2 (GTK+ 2.24.30; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Wed, 20 Jul 2016 12:21:04 +0200 Daniel Vetter wrote: > In the transformation of this to sphinx we've forgotten to remove the > old .txt file. We didn't quite forget...Jani sent the patch but I didn't feel quite right about applying it. People "know" that kernel-doc-nano-HOWTO.txt is there, and various other docs had pointers to it. So I've just committed this instead, hope it's OK... jon --- >From 8ed292fe864e9ed7d335515e97590122a56d7cba Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 20 Jul 2016 16:43:41 -0600 Subject: [PATCH] docs: deprecate kernel-doc-nano-HOWTO.txt Now that the new Sphinx world order is taking over, the information in kernel-doc-nano-HOWTO.txt is outmoded. I hate to remove it altogether, since it's one of those files that people expect to find. But we can add a warning and fix all the other pointers to it. Reminded-by: Daniel Vetter Signed-off-by: Jonathan Corbet --- Documentation/00-INDEX | 4 ++-- Documentation/CodingStyle | 2 +- Documentation/development-process/4.Coding | 2 +- Documentation/kernel-doc-nano-HOWTO.txt | 3 +++ Documentation/zh_CN/CodingStyle | 2 +- 5 files changed, 8 insertions(+), 5 deletions(-) -- 2.7.4 diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index cd077ca0e1b8..cb9a6c6fa83b 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -255,10 +255,10 @@ kbuild/ - directory with info about the kernel build process. kdump/ - directory with mini HowTo on getting the crash dump code to work. -kernel-doc-nano-HOWTO.txt - - mini HowTo on generation and location of kernel documentation files. kernel-docs.txt - listing of various WWW + books that document kernel internals. +kernel-documentation.rst + - how to write and format reStructuredText kernel documentation kernel-parameters.txt - summary listing of command line / boot prompt args for the kernel. kernel-per-CPU-kthreads.txt diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle index 9a70ddd16584..a096836723ca 100644 --- a/Documentation/CodingStyle +++ b/Documentation/CodingStyle @@ -458,7 +458,7 @@ of the function, telling people what it does, and possibly WHY it does it. When commenting the kernel API functions, please use the kernel-doc format. -See the files Documentation/kernel-doc-nano-HOWTO.txt and scripts/kernel-doc +See the files Documentation/kernel-documentation.rst and scripts/kernel-doc for details. Linux style for comments is the C89 "/* ... */" style. diff --git a/Documentation/development-process/4.Coding b/Documentation/development-process/4.Coding index e3cb6a56653a..9a3ee77cefb1 100644 --- a/Documentation/development-process/4.Coding +++ b/Documentation/development-process/4.Coding @@ -346,7 +346,7 @@ which have not been so documented, there is no harm in adding kerneldoc comments for the future; indeed, this can be a useful activity for beginning kernel developers. The format of these comments, along with some information on how to create kerneldoc templates can be found in the file -Documentation/kernel-doc-nano-HOWTO.txt. +Documentation/kernel-documentation.rst. Anybody who reads through a significant amount of existing kernel code will note that, often, comments are most notable by their absence. Once again, diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt index 78f69cdc9b3f..062e3af271b7 100644 --- a/Documentation/kernel-doc-nano-HOWTO.txt +++ b/Documentation/kernel-doc-nano-HOWTO.txt @@ -1,3 +1,6 @@ +NOTE: this document is outdated and will eventually be removed. See +Documentation/kernel-documentation.rst for current information. + kernel-doc nano-HOWTO ===================== diff --git a/Documentation/zh_CN/CodingStyle b/Documentation/zh_CN/CodingStyle index bbb9d6ae05ca..12717791baac 100644 --- a/Documentation/zh_CN/CodingStyle +++ b/Documentation/zh_CN/CodingStyle @@ -399,7 +399,7 @@ C是一个简朴的语言，你的命名也应该这样。和 Modula-2 和 Pasca 些事情的原因。 当注释内核API函数时，请使用 kernel-doc 格式。请看 -Documentation/kernel-doc-nano-HOWTO.txt和scripts/kernel-doc 以获得详细信息。 +Documentation/kernel-documentation.rst和scripts/kernel-doc 以获得详细信息。 Linux的注释风格是 C89 “/* ... */” 风格。不要使用 C99 风格 “// ...” 注释。