| Message ID | 20231228100608.3123987-1-vegard.nossum@oracle.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | [-next] fs: fix __sb_write_started() kerneldoc formatting | expand |
On Thu, 28 Dec 2023 11:06:08 +0100, Vegard Nossum wrote: > When running 'make htmldocs', I see the following warning: > > Documentation/filesystems/api-summary:14: ./include/linux/fs.h:1659: WARNING: Definition list ends without a blank line; unexpected unindent. > > The official guidance [1] seems to be to use lists, which will prevent > both the "unexpected unindent" warning as well as ensure that each line > is formatted on a separate line in the HTML output instead of being > all considered a single paragraph. > > [...] Applied to the vfs.rw branch of the vfs/vfs.git tree. Patches in the vfs.rw branch should appear in linux-next soon. Please report any outstanding bugs that were missed during review in a new review to the original patch series allowing us to drop it. It's encouraged to provide Acked-bys and Reviewed-bys even though the patch has now been applied. If possible patch trailers will be updated. Note that commit hashes shown below are subject to change due to rebase, trailer updates or similar. If in doubt, please check the listed branch. tree: https://git.kernel.org/pub/scm/linux/kernel/git/vfs/vfs.git branch: vfs.rw [1/1] fs: fix __sb_write_started() kerneldoc formatting https://git.kernel.org/vfs/vfs/c/c39e2ae3943d
On Thu 28-12-23 11:06:08, Vegard Nossum wrote: > When running 'make htmldocs', I see the following warning: > > Documentation/filesystems/api-summary:14: ./include/linux/fs.h:1659: WARNING: Definition list ends without a blank line; unexpected unindent. > > The official guidance [1] seems to be to use lists, which will prevent > both the "unexpected unindent" warning as well as ensure that each line > is formatted on a separate line in the HTML output instead of being > all considered a single paragraph. > > [1]: https://docs.kernel.org/doc-guide/kernel-doc.html#return-values > > Fixes: 8802e580ee64 ("fs: create __sb_write_started() helper") > Cc: Amir Goldstein <amir73il@gmail.com> > Cc: Josef Bacik <josef@toxicpanda.com> > Cc: Jan Kara <jack@suse.cz> > Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> Thanks! Feel free to add: Reviewed-by: Jan Kara <jack@suse.cz> Honza > --- > Applies to git://git.kernel.org/pub/scm/linux/kernel/git/vfs/vfs.git vfs.rw > > include/linux/fs.h | 6 +++--- > 1 file changed, 3 insertions(+), 3 deletions(-) > > diff --git a/include/linux/fs.h b/include/linux/fs.h > index db5d07e6e02e..473063f385e5 100644 > --- a/include/linux/fs.h > +++ b/include/linux/fs.h > @@ -1650,9 +1650,9 @@ static inline bool __sb_start_write_trylock(struct super_block *sb, int level) > * @sb: the super we write to > * @level: the freeze level > * > - * > 0 sb freeze level is held > - * 0 sb freeze level is not held > - * < 0 !CONFIG_LOCKDEP/LOCK_STATE_UNKNOWN > + * * > 0 - sb freeze level is held > + * * 0 - sb freeze level is not held > + * * < 0 - !CONFIG_LOCKDEP/LOCK_STATE_UNKNOWN > */ > static inline int __sb_write_started(const struct super_block *sb, int level) > { > -- > 2.34.1 >
diff --git a/include/linux/fs.h b/include/linux/fs.h index db5d07e6e02e..473063f385e5 100644 --- a/include/linux/fs.h +++ b/include/linux/fs.h @@ -1650,9 +1650,9 @@ static inline bool __sb_start_write_trylock(struct super_block *sb, int level) * @sb: the super we write to * @level: the freeze level * - * > 0 sb freeze level is held - * 0 sb freeze level is not held - * < 0 !CONFIG_LOCKDEP/LOCK_STATE_UNKNOWN + * * > 0 - sb freeze level is held + * * 0 - sb freeze level is not held + * * < 0 - !CONFIG_LOCKDEP/LOCK_STATE_UNKNOWN */ static inline int __sb_write_started(const struct super_block *sb, int level) {
When running 'make htmldocs', I see the following warning: Documentation/filesystems/api-summary:14: ./include/linux/fs.h:1659: WARNING: Definition list ends without a blank line; unexpected unindent. The official guidance [1] seems to be to use lists, which will prevent both the "unexpected unindent" warning as well as ensure that each line is formatted on a separate line in the HTML output instead of being all considered a single paragraph. [1]: https://docs.kernel.org/doc-guide/kernel-doc.html#return-values Fixes: 8802e580ee64 ("fs: create __sb_write_started() helper") Cc: Amir Goldstein <amir73il@gmail.com> Cc: Josef Bacik <josef@toxicpanda.com> Cc: Jan Kara <jack@suse.cz> Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> --- Applies to git://git.kernel.org/pub/scm/linux/kernel/git/vfs/vfs.git vfs.rw include/linux/fs.h | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)