From mboxrd@z Thu Jan  1 00:00:00 1970
From: "Tobin C. Harding" <me@tobin.cc>
Subject: Re: [PATCH] jbd2: fix sphinx kerel-doc build warnings for journal_s
Date: Tue, 9 Jan 2018 07:32:43 +1100
Message-ID: <20180108203243.GB2462@eros>
References: <1515285974-29373-1-git-send-email-me@tobin.cc>
 <20180108151604.v4kfq47dc4cpcdxw@quack2.suse.cz>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Cc: Theodore Ts'o <tytso@mit.edu>, Jan Kara <jack@suse.com>,
        linux-ext4@vger.kernel.org, linux-kernel@vger.kernel.org
To: Jan Kara <jack@suse.cz>
Return-path: <linux-kernel-owner@vger.kernel.org>
Content-Disposition: inline
In-Reply-To: <20180108151604.v4kfq47dc4cpcdxw@quack2.suse.cz>
Sender: linux-kernel-owner@vger.kernel.org
List-Id: linux-ext4.vger.kernel.org

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.