[PATCH] jbd2: document the h_invalid handle flag

[PATCH] jbd2: document the h_invalid handle flag

[Amit Patole]

Commit 61e2a90a910c ("ext4: enable scoped NOFS when starting a handle
in nojournal mode") added the h_invalid bit to struct
jbd2_journal_handle but did not add it to the kernel-doc comment above
the structure, so kernel-doc now warns:

  include/linux/jbd2.h:523 struct member 'h_invalid' not described in
  'jbd2_journal_handle'

Describe the new flag. It is set by ext4_get_nojournal() on a handle
that is not attached to any journal and is tested by
ext4_handle_valid().

The warning was found by running scripts/kernel-doc over the headers
pulled into the htmldocs build. An AI coding assistant (Claude Opus
5.5) was used to locate the warning and draft this change; it was
verified with scripts/kernel-doc (no warnings left) and checkpatch.

Fixes: 61e2a90a910c ("ext4: enable scoped NOFS when starting a handle in nojournal mode")
Signed-off-by: Amit Patole <amit.patole@gmail.com>
---
Comment-only change. Built with W=1 on x86_64 (fs/jbd2/, fs/ext4/)
with no new warnings.
---
 include/linux/jbd2.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/include/linux/jbd2.h b/include/linux/jbd2.h
index e3886963ba00..69f12366a09a 100644
--- a/include/linux/jbd2.h
+++ b/include/linux/jbd2.h
@@ -482,6 +482,7 @@ struct jbd2_revoke_table_s;
  * @h_sync: Flag for sync-on-close.
  * @h_reserved: Flag for handle for reserved credits.
  * @h_aborted: Flag indicating fatal error on handle.
+ * @h_invalid: Flag for a handle not attached to a journal (ext4 nojournal mode).
  * @h_type: For handle statistics.
  * @h_line_no: For handle statistics.
  * @h_start_jiffies: Handle Start time.

---
base-commit: 05441d697f7f9a927264f4058cbbc6a03dfcac9d
change-id: 20261105-kdoc-jbd2-h_invalid-8297dd06f190

Best regards,
--  
Amit Patole <amit.patole@gmail.com>

Re: [PATCH] jbd2: document the h_invalid handle flag

[Jan Kara]

On Thu 05-11-26 09:00:36, Amit Patole wrote:
> Commit 61e2a90a910c ("ext4: enable scoped NOFS when starting a handle
> in nojournal mode") added the h_invalid bit to struct
> jbd2_journal_handle but did not add it to the kernel-doc comment above
> the structure, so kernel-doc now warns:
> 
>   include/linux/jbd2.h:523 struct member 'h_invalid' not described in
>   'jbd2_journal_handle'
> 
> Describe the new flag. It is set by ext4_get_nojournal() on a handle
> that is not attached to any journal and is tested by
> ext4_handle_valid().
> 
> The warning was found by running scripts/kernel-doc over the headers
> pulled into the htmldocs build. An AI coding assistant (Claude Opus
> 5.5) was used to locate the warning and draft this change; it was
> verified with scripts/kernel-doc (no warnings left) and checkpatch.
> 
> Fixes: 61e2a90a910c ("ext4: enable scoped NOFS when starting a handle in nojournal mode")
> Signed-off-by: Amit Patole <amit.patole@gmail.com>

Looks good. Feel free to add:

Reviewed-by: Jan Kara <jack@suse.cz>

								Honza

> ---
> Comment-only change. Built with W=1 on x86_64 (fs/jbd2/, fs/ext4/)
> with no new warnings.
> ---
>  include/linux/jbd2.h | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/include/linux/jbd2.h b/include/linux/jbd2.h
> index e3886963ba00..69f12366a09a 100644
> --- a/include/linux/jbd2.h
> +++ b/include/linux/jbd2.h
> @@ -482,6 +482,7 @@ struct jbd2_revoke_table_s;
>   * @h_sync: Flag for sync-on-close.
>   * @h_reserved: Flag for handle for reserved credits.
>   * @h_aborted: Flag indicating fatal error on handle.
> + * @h_invalid: Flag for a handle not attached to a journal (ext4 nojournal mode).
>   * @h_type: For handle statistics.
>   * @h_line_no: For handle statistics.
>   * @h_start_jiffies: Handle Start time.
> 
> ---
> base-commit: 05441d697f7f9a927264f4058cbbc6a03dfcac9d
> change-id: 20261105-kdoc-jbd2-h_invalid-8297dd06f190
> 
> Best regards,
> --  
> Amit Patole <amit.patole@gmail.com>
> 
-- 
Jan Kara <jack@suse.com>
SUSE Labs, CR