Skip to content
  • Danilo Cesar Lemes de Paula's avatar
    scripts/kernel-doc Allow struct arguments documentation in struct body · a4c6ebed
    Danilo Cesar Lemes de Paula authored
    
    
    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: default avatarDanilo 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: default avatarJonathan Corbet <corbet@lwn.net>
    a4c6ebed