From patchwork Mon Dec 18 12:30:04 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 10119229 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 67D1160390 for ; Mon, 18 Dec 2017 12:30:37 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 59B28285BA for ; Mon, 18 Dec 2017 12:30:37 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 4E82528FBA; Mon, 18 Dec 2017 12:30:37 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.9 required=2.0 tests=BAYES_00,RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id D6693285BA for ; Mon, 18 Dec 2017 12:30:36 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1759107AbdLRMae (ORCPT ); Mon, 18 Dec 2017 07:30:34 -0500 Received: from osg.samsung.com ([64.30.133.232]:44978 "EHLO osg.samsung.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1759067AbdLRMad (ORCPT ); Mon, 18 Dec 2017 07:30:33 -0500 Received: from localhost (localhost [127.0.0.1]) by osg.samsung.com (Postfix) with ESMTP id EDA623241B; Mon, 18 Dec 2017 04:30:32 -0800 (PST) X-Virus-Scanned: Debian amavisd-new at dev.s-opensource.com X-Amavis-Alert: BAD HEADER SECTION, Duplicate header field: "References" Received: from osg.samsung.com ([127.0.0.1]) by localhost (localhost [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id YGxayDZsOK17; Mon, 18 Dec 2017 04:30:31 -0800 (PST) Received: from smtp.s-opensource.com (177.133.94.85.dynamic.adsl.gvt.net.br [177.133.94.85]) by osg.samsung.com (Postfix) with ESMTPSA id 7CC41323B2; Mon, 18 Dec 2017 04:30:24 -0800 (PST) Received: from mchehab by smtp.s-opensource.com with local (Exim 4.89) (envelope-from ) id 1eQuYn-000385-Pj; Mon, 18 Dec 2017 10:30:21 -0200 From: Mauro Carvalho Chehab To: Linux Media Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , Linux Doc Mailing List , Tom Saeger Subject: [PATCH v4 03/18] docs: kernel-doc.rst: improve function documentation section Date: Mon, 18 Dec 2017 10:30:04 -0200 Message-Id: <14b56bdd877409489a5c960300c113c014a755d6.1513599193.git.mchehab@s-opensource.com> X-Mailer: git-send-email 2.14.3 In-Reply-To: References: In-Reply-To: References: Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Move its contents to happen earlier and improve the description of return values, adding a subsection to it. Most of the contents there came from kernel-doc-nano-HOWTO.txt. Signed-off-by: Mauro Carvalho Chehab --- Documentation/doc-guide/kernel-doc.rst | 100 ++++++++++++++++++++------------- 1 file changed, 61 insertions(+), 39 deletions(-) diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index 7cf58c3489de..3aac228fc346 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -197,6 +197,67 @@ Example:: int d; }; +Function documentation +---------------------- + +The general format of a function and function-like macro kernel-doc comment is:: + + /** + * function_name() - Brief description of function. + * @arg1: Describe the first argument. + * @arg2: Describe the second argument. + * One can provide multiple line descriptions + * for arguments. + * + * A longer description, with more discussion of the function function_name() + * that might be useful to those using or modifying it. Begins with an + * empty comment line, and may include additional embedded empty + * comment lines. + * + * The longer description may have multiple paragraphs. + * + * Return: Describe the return value of foobar. + * + * The return value description can also have multiple paragraphs, and should + * be placed at the end of the comment block. + */ + +The brief description following the function name may span multiple lines, and +ends with an argument description, a blank comment line, or the end of the +comment block. + +Return values +~~~~~~~~~~~~~ + +The return value, if any, should be described in a dedicated section +named ``Return``. + +.. note:: + + #) The multi-line descriptive text you provide does *not* recognize + line breaks, so if you try to format some text nicely, as in:: + + * Return: + * 0 - OK + * -EINVAL - invalid argument + * -ENOMEM - out of memory + + this will all run together and produce:: + + Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory + + So, in order to produce the desired line breaks, you need to use a + ReST list, e. g.:: + + * Return: + * * 0 - OK to runtime suspend the device + * * -EBUSY - Device should not be runtime suspended + + #) If the descriptive text you provide has lines that begin with + some phrase followed by a colon, each of those phrases will be taken + as a new section heading, with probably won't produce the desired + effect. + Highlights and cross-references ------------------------------- @@ -269,45 +330,6 @@ cross-references. For further details, please refer to the `Sphinx C Domain`_ documentation. -Function documentation ----------------------- - -The general format of a function and function-like macro kernel-doc comment is:: - - /** - * function_name() - Brief description of function. - * @arg1: Describe the first argument. - * @arg2: Describe the second argument. - * One can provide multiple line descriptions - * for arguments. - * - * A longer description, with more discussion of the function function_name() - * that might be useful to those using or modifying it. Begins with an - * empty comment line, and may include additional embedded empty - * comment lines. - * - * The longer description may have multiple paragraphs. - * - * Return: Describe the return value of foobar. - * - * The return value description can also have multiple paragraphs, and should - * be placed at the end of the comment block. - */ - -The brief description following the function name may span multiple lines, and -ends with an ``@argument:`` description, a blank comment line, or the end of the -comment block. - -The kernel-doc function comments describe each parameter to the function, in -order, with the ``@argument:`` descriptions. The ``@argument:`` descriptions -must begin on the very next line following the opening brief function -description line, with no intervening blank comment lines. The ``@argument:`` -descriptions may span multiple lines. The continuation lines may contain -indentation. If a function parameter is ``...`` (varargs), it should be listed -in kernel-doc notation as: ``@...:``. - -The return value, if any, should be described in a dedicated section at the end -of the comment starting with "Return:". Structure, union, and enumeration documentation -----------------------------------------------