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 Mon, Jan 08, 2018 at 04:16:04PM +0100, Jan Kara wrote:
    > 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...

    Oh that looks much nicer. I'll have another play with it and re-spin.

    thanks,
    Tobin.

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