lkml.org 
[lkml]   [2018]   [Jan]   [8]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [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@tobin.cc>

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

Acked-by: Jan Kara <jack@suse.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@suse.com>
SUSE Labs, CR

\
 
 \ /
  Last update: 2018-01-14 23:17    [W:0.067 / U:0.148 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site