From patchwork Wed Oct 4 11:48:40 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: 9984421 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 9656260365 for ; Wed, 4 Oct 2017 12:00:31 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 8866F28AF6 for ; Wed, 4 Oct 2017 12:00:31 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 7D00528AF1; Wed, 4 Oct 2017 12:00:31 +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=unavailable 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 E3AD728AF6 for ; Wed, 4 Oct 2017 12:00:30 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752310AbdJDMAS (ORCPT ); Wed, 4 Oct 2017 08:00:18 -0400 Received: from osg.samsung.com ([64.30.133.232]:61934 "EHLO osg.samsung.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752011AbdJDL6h (ORCPT ); Wed, 4 Oct 2017 07:58:37 -0400 Received: from localhost (localhost [127.0.0.1]) by osg.samsung.com (Postfix) with ESMTP id 5B5FF2A493; Wed, 4 Oct 2017 04:49:14 -0700 (PDT) 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 aKsZJUSyL7f5; Wed, 4 Oct 2017 04:49:13 -0700 (PDT) Received: from smtp.s-opensource.com (177.43.29.231.dynamic.adsl.gvt.net.br [177.43.29.231]) by osg.samsung.com (Postfix) with ESMTPSA id C2EC32A41E; Wed, 4 Oct 2017 04:49:02 -0700 (PDT) Received: from mchehab by smtp.s-opensource.com with local (Exim 4.89) (envelope-from ) id 1dziAb-00088G-T3; Wed, 04 Oct 2017 08:48:57 -0300 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Linux Media Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , Daniel Vetter Subject: [PATCH v3 02/17] docs: kernel-doc.rst: improve private members description Date: Wed, 4 Oct 2017 08:48:40 -0300 Message-Id: X-Mailer: git-send-email 2.13.6 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 The private members section can now be moved to be together with the arguments section. Move it there and add an example about the usage of public: Signed-off-by: Mauro Carvalho Chehab --- Documentation/doc-guide/kernel-doc.rst | 56 ++++++++++++++++++---------------- 1 file changed, 30 insertions(+), 26 deletions(-) diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index 662755f830d5..146041fc494a 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -167,6 +167,36 @@ notation as:: * @...: description +Private members +~~~~~~~~~~~~~~~ + +Inside a struct or union description, you can use the ``private:`` and +``public:`` comment tags. Structure fields that are inside a ``private:`` +area are not listed in the generated output documentation. + +The ``private:`` and ``public:`` tags must begin immediately following a +``/*`` comment marker. They may optionally include comments between the +``:`` and the ending ``*/`` marker. + +Example:: + + /** + * struct my_struct - short description + * @a: first member + * @b: second member + * @d: fourth member + * + * Longer description + */ + struct my_struct { + int a; + int b; + /* private: internal use only */ + int c; + /* public: the next one is public */ + int d; + }; + Highlights and cross-references ------------------------------- @@ -332,32 +362,6 @@ on a line of their own, like all other kernel-doc comments:: int foobar; } -Private members -~~~~~~~~~~~~~~~ - -Inside a struct description, you can use the "private:" and "public:" comment -tags. Structure fields that are inside a "private:" area are not listed in the -generated output documentation. The "private:" and "public:" tags must begin -immediately following a ``/*`` comment marker. They may optionally include -comments between the ``:`` and the ending ``*/`` marker. - -Example:: - - /** - * struct my_struct - short description - * @a: first member - * @b: second member - * - * Longer description - */ - struct my_struct { - int a; - int b; - /* private: internal use only */ - int c; - }; - - Typedef documentation ---------------------