scripts/kernel-doc Allow struct arguments documentation in struct body
authorDanilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk>
Tue, 4 Aug 2015 12:04:08 +0000 (09:04 -0300)
committerJonathan Corbet <corbet@lwn.net>
Thu, 6 Aug 2015 19:05:35 +0000 (13:05 -0600)
commita4c6ebede2f99fc3aaa5a42228a16747d0aa2504
tree14b2121cd22d9e58e10ec07c05d963740142aeb1
parent64e32895f9d87aaa0842c07d0b17f4895955db20
scripts/kernel-doc Allow struct arguments documentation in struct body

Describing arguments at top of a struct definition works fine
for small/medium size structs, but it definitely doesn't work well
for struct with a huge list of elements.

Keeping the arguments list inside the struct body makes it easier
to maintain the documentation.
ie:
/**
 * struct my_struct - short description
 * @a: first member
 * @b: second member
 *
 * Longer description
 */
struct my_struct {
    int a;
    int b;
    /**
     * @c: This is longer description of C
     *
     * You can use paragraphs to describe arguments
     * using this method.
     */
    int c;
};

This patch allows the use of this kind of syntax. Only one argument
per comment and user can use how many paragraphs he needs. It should
start with /**, which is already being used by kernel-doc. If those
comment doesn't follow those rules, it will be ignored.

Signed-off-by: Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk>
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Herbert Xu <herbert@gondor.apana.org.au>
Cc: Stephan Mueller <smueller@chronox.de>
Cc: Michal Marek <mmarek@suse.cz>
Cc: linux-kernel@vger.kernel.org
Cc: linux-doc@vger.kernel.org
Cc: intel-gfx <intel-gfx@lists.freedesktop.org>
Cc: dri-devel <dri-devel@lists.freedesktop.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
scripts/kernel-doc