From mboxrd@z Thu Jan 1 00:00:00 1970 Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932814AbeAHPQJ (ORCPT + 1 other); Mon, 8 Jan 2018 10:16:09 -0500 Received: from mx2.suse.de ([195.135.220.15]:48645 "EHLO mx2.suse.de" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S932606AbeAHPQH (ORCPT ); Mon, 8 Jan 2018 10:16:07 -0500 Date: Mon, 8 Jan 2018 16:16:04 +0100 From: Jan Kara To: "Tobin C. Harding" Cc: Theodore Ts'o , Jan Kara , linux-ext4@vger.kernel.org, linux-kernel@vger.kernel.org Subject: Re: [PATCH] jbd2: fix sphinx kerel-doc build warnings for journal_s Message-ID: <20180108151604.v4kfq47dc4cpcdxw@quack2.suse.cz> References: <1515285974-29373-1-git-send-email-me@tobin.cc> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <1515285974-29373-1-git-send-email-me@tobin.cc> User-Agent: NeoMutt/20170421 (1.8.2) Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Return-Path: 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 This is probably better than having documentation in two places so: Acked-by: Jan Kara 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 SUSE Labs, CR