linux-kernel - Re: [PATCH] jbd2: fix sphinx kerel-doc build warnings for journal

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20180108151604.v4kfq47dc4cpcdxw@quack2.suse.cz>
Date:   Mon, 8 Jan 2018 16:16:04 +0100
From:   Jan Kara <jack@...e.cz>
To:     "Tobin C. Harding" <me@...in.cc>
Cc:     Theodore Ts'o <tytso@....edu>, Jan Kara <jack@...e.com>,
        linux-ext4@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: [PATCH] jbd2: fix sphinx kerel-doc build warnings for journal_s

On Sun 07-01-18 11:46:14, Tobin C. Harding wrote:
> Sphinx emits various warnings when building make target 'htmldocs'.
> 
> Currently struct journal_s definition contains duplicate documentation,
> some as kernel-docs and some as standard c89 comments.  We can reduce
> duplication while cleaning up the kernel-docs. 
> 
> Move all kernel-docs to right above each struct member.  Use the set of
> all existing comments (kernel-doc and c89).
> 
> Signed-off-by: Tobin C. Harding <me@...in.cc>

This is probably better than having documentation in two places so:

Acked-by: Jan Kara <jack@...e.cz>

Just one nit below:

>  struct journal_s
>  {
> -	/* General journaling state flags [j_state_lock] */
> +	/**
> +	 * @j_flags:
> +	 *
> +	 * General journaling state flags [j_state_lock]
> +	 */

Won't it be possible in cases like this to fold the name and description
into one line? Like:

	/**
	 * @j_flags: General journaling state flags [j_state_lock]
	 */

That would save a lot of vertical space...

								Honza
-- 
Jan Kara <jack@...e.com>
SUSE Labs, CR