[PATCH -next] fs: fix __sb_write_started() kerneldoc formatting

[PATCH -next] fs: fix __sb_write_started() kerneldoc formatting

[Vegard Nossum]

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(-)

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

Re: [PATCH -next] fs: fix __sb_write_started() kerneldoc formatting

[Christian Brauner]

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

Re: [PATCH -next] fs: fix __sb_write_started() kerneldoc formatting

[Jan Kara]

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
> 
-- 
Jan Kara <jack@suse.com>
SUSE Labs, CR