Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S969611AbdIZR7b (ORCPT ); Tue, 26 Sep 2017 13:59:31 -0400 Received: from ec2-52-27-115-49.us-west-2.compute.amazonaws.com ([52.27.115.49]:55731 "EHLO osg.samsung.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S969481AbdIZR71 (ORCPT ); Tue, 26 Sep 2017 13:59:27 -0400 X-Amavis-Alert: BAD HEADER SECTION, Duplicate header field: "References" From: Mauro Carvalho Chehab To: Linux Media Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , Linux Doc Mailing List , linux-kernel@vger.kernel.org, Daniel Vetter Subject: [PATCH 05/10] docs: kernel-doc.rst: improve structs chapter Date: Tue, 26 Sep 2017 14:59:15 -0300 Message-Id: X-Mailer: git-send-email 2.13.5 In-Reply-To: References: In-Reply-To: References: Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 2986 Lines: 82 There is a mess on this chapter: it suggests that even enums and unions should be documented with "struct". That's not the way it should be ;-) Fix it and move it to happen earlier. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Mauro Carvalho Chehab --- Documentation/doc-guide/kernel-doc.rst | 48 +++++++++++++++++----------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index 9b69dfe928d8..68cb1b496c73 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -258,6 +258,30 @@ named ``Return``. as a new section heading, with probably won't produce the desired effect. +Structure, union, and enumeration documentation +----------------------------------------------- + +The general format of a struct, union, and enum kernel-doc comment is:: + + /** + * struct struct_name - Brief description. + * @argument: Description of member member_name. + * + * Description of the structure. + */ + +On the above, ``struct`` is used to mean structs. You can also use ``union`` +and ``enum`` to describe unions and enums. ``argument`` is used +to mean struct and union member names as well as enumerations in an enum. + +The brief description following the structure name may span multiple lines, and +ends with a member description, a blank comment line, or the end of the +comment block. + +The kernel-doc data structure comments describe each member of the structure, +in order, with the member descriptions. + + Highlights and cross-references ------------------------------- @@ -331,30 +355,6 @@ cross-references. For further details, please refer to the `Sphinx C Domain`_ documentation. -Structure, union, and enumeration documentation ------------------------------------------------ - -The general format of a struct, union, and enum kernel-doc comment is:: - - /** - * struct struct_name - Brief description. - * @member_name: Description of member member_name. - * - * Description of the structure. - */ - -Below, "struct" is used to mean structs, unions and enums, and "member" is used -to mean struct and union members as well as enumerations in an enum. - -The brief description following the structure name may span multiple lines, and -ends with a ``@member:`` description, a blank comment line, or the end of the -comment block. - -The kernel-doc data structure comments describe each member of the structure, in -order, with the ``@member:`` descriptions. The ``@member:`` descriptions must -begin on the very next line following the opening brief function description -line, with no intervening blank comment lines. The ``@member:`` descriptions may -span multiple lines. The continuation lines may contain indentation. In-line member documentation comments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- 2.13.5