jbd2: fix sphinx kernel-doc build warnings

Sphinx emits various (26) warnings when building make target 'htmldocs'. Currently struct definitions contain 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). Add documentation for missing struct members and function arguments. Signed-off-by: Tobin C. Harding <[email protected]> Signed-off-by: Theodore Ts'o <[email protected]> Cc: [email protected]
chewitt · Jan 10, 2018 · f69120c · f69120c
1 parent abbc3f9
commit f69120c
Show file tree

Hide file tree

Showing 2 changed files with 272 additions and 164 deletions.
diff --git a/fs/jbd2/transaction.c b/fs/jbd2/transaction.c
@@ -492,8 +492,10 @@ void jbd2_journal_free_reserved(handle_t *handle)
 EXPORT_SYMBOL(jbd2_journal_free_reserved);
 
 /**
- * int jbd2_journal_start_reserved(handle_t *handle) - start reserved handle
+ * int jbd2_journal_start_reserved() - start reserved handle
  * @handle: handle to start
+ * @type: for handle statistics
+ * @line_no: for handle statistics
  *
  * Start handle that has been previously reserved with jbd2_journal_reserve().
  * This attaches @handle to the running transaction (or creates one if there's
@@ -623,6 +625,7 @@ int jbd2_journal_extend(handle_t *handle, int nblocks)
  * int jbd2_journal_restart() - restart a handle .
  * @handle:  handle to restart
  * @nblocks: nr credits requested
+ * @gfp_mask: memory allocation flags (for start_this_handle)
  *
  * Restart a handle for a multi-transaction filesystem
  * operation.