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@xxxxxxxx>
>
> This is probably better than having documentation in two places so:
>
> Acked-by: Jan Kara <jack@xxxxxxx>
>
> 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.
