lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
Open Source and information security mailing list archives
| ||
|
Date: Tue, 9 Jan 2018 07:32:43 +1100 From: "Tobin C. Harding" <me@...in.cc> To: Jan Kara <jack@...e.cz> Cc: Theodore Ts'o <tytso@....edu>, Jan Kara <jack@...e.com>, linux-ext4@...r.kernel.org, linux-kernel@...r.kernel.org Subject: Re: [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@...in.cc> > > This is probably better than having documentation in two places so: > > Acked-by: Jan Kara <jack@...e.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.
Powered by blists - more mailing lists