[PATCH] dm: vdo: fix kernel-doc warnings in admin-state.c

[PATCH] dm: vdo: fix kernel-doc warnings in admin-state.c

[Sunday Adelodun]

Several functions in admin-state.c were missing parameter descriptions
leading to multiple kernel-doc warnings during build.

Update the affected comments by adding missing @state, @operation,
@waiter, @initiator, @result, and other parameter descriptions.

No functional changes.

Signed-off-by: Sunday Adelodun <adelodunolaoluwa@yahoo.com>
---
 drivers/md/dm-vdo/admin-state.c | 74 ++++++++++++++++++++++-----------
 1 file changed, 49 insertions(+), 25 deletions(-)

diff --git a/drivers/md/dm-vdo/admin-state.c b/drivers/md/dm-vdo/admin-state.c
index 3f9dba525154..eedbe080f632 100644
--- a/drivers/md/dm-vdo/admin-state.c
+++ b/drivers/md/dm-vdo/admin-state.c
@@ -187,6 +187,8 @@ static const struct admin_state_code *get_next_state(const struct admin_state *s
 
 /**
  * vdo_finish_operation() - Finish the current operation.
+ * @state: The admin_state object representing the current operation.
+ * @result: The result code to pass to any waiting completion handler.
  *
  * Will notify the operation waiter if there is one. This method should be used for operations
  * started with vdo_start_operation(). For operations which were started with vdo_start_draining(),
@@ -214,8 +216,10 @@ bool vdo_finish_operation(struct admin_state *state, int result)
 
 /**
  * begin_operation() - Begin an operation if it may be started given the current state.
- * @waiter A completion to notify when the operation is complete; may be NULL.
- * @initiator The vdo_admin_initiator_fn to call if the operation may begin; may be NULL.
+ * @state: The admin_state object representing the current administrative state.
+ * @operation: The state code describing the operation to begin.
+ * @waiter: A completion to notify when the operation is complete; may be NULL.
+ * @initiator: The vdo_admin_initiator_fn to call if the operation may begin; may be NULL.
  *
  * Return: VDO_SUCCESS or an error.
  */
@@ -259,8 +263,10 @@ static int __must_check begin_operation(struct admin_state *state,
 
 /**
  * start_operation() - Start an operation if it may be started given the current state.
- * @waiter     A completion to notify when the operation is complete.
- * @initiator The vdo_admin_initiator_fn to call if the operation may begin; may be NULL.
+ * @state: The admin_state object representing the current administrative state.
+ * @operation: The state code describing the operation to begin.
+ * @waiter:     A completion to notify when the operation is complete.
+ * @initiator: The vdo_admin_initiator_fn to call if the operation may begin; may be NULL.
  *
  * Return: true if the operation was started.
  */
@@ -274,10 +280,10 @@ static inline bool __must_check start_operation(struct admin_state *state,
 
 /**
  * check_code() - Check the result of a state validation.
- * @valid true if the code is of an appropriate type.
- * @code The code which failed to be of the correct type.
- * @what What the code failed to be, for logging.
- * @waiter The completion to notify of the error; may be NULL.
+ * @valid: true if the code is of an appropriate type.
+ * @code: The code which failed to be of the correct type.
+ * @what: What the code failed to be, for logging.
+ * @waiter: The completion to notify of the error; may be NULL.
  *
  * If the result failed, log an invalid state error and, if there is a waiter, notify it.
  *
@@ -301,7 +307,8 @@ static bool check_code(bool valid, const struct admin_state_code *code, const ch
 
 /**
  * assert_vdo_drain_operation() - Check that an operation is a drain.
- * @waiter The completion to finish with an error if the operation is not a drain.
+ * @operation: The drain operation type to check.
+ * @waiter: The completion to finish with an error if the operation is not a drain.
  *
  * Return: true if the specified operation is a drain.
  */
@@ -313,11 +320,12 @@ static bool __must_check assert_vdo_drain_operation(const struct admin_state_cod
 
 /**
  * vdo_start_draining() - Initiate a drain operation if the current state permits it.
- * @operation The type of drain to initiate.
- * @waiter The completion to notify when the drain is complete.
- * @initiator The vdo_admin_initiator_fn to call if the operation may begin; may be NULL.
+ * @state: The admin_state object representing the current administrative state.
+ * @operation: The type of drain to initiate.
+ * @waiter: The completion to notify when the drain is complete.
+ * @initiator: The vdo_admin_initiator_fn to call if the operation may begin; may be NULL.
  *
- * Return: true if the drain was initiated, if not the waiter will be notified.
+ * Return: true if the drain was initiated; otherwise false, with the waiter notified.
  */
 bool vdo_start_draining(struct admin_state *state,
 			const struct admin_state_code *operation,
@@ -345,6 +353,7 @@ bool vdo_start_draining(struct admin_state *state,
 
 /**
  * vdo_finish_draining() - Finish a drain operation if one was in progress.
+ * @state: The admin_state object representing the current administrative state.
  *
  * Return: true if the state was draining; will notify the waiter if so.
  */
@@ -355,6 +364,8 @@ bool vdo_finish_draining(struct admin_state *state)
 
 /**
  * vdo_finish_draining_with_result() - Finish a drain operation with a status code.
+ * @state: The admin_state object representing the current administrative state.
+ * @result: The result code to return to the waiting completion.
  *
  * Return: true if the state was draining; will notify the waiter if so.
  */
@@ -365,7 +376,8 @@ bool vdo_finish_draining_with_result(struct admin_state *state, int result)
 
 /**
  * vdo_assert_load_operation() - Check that an operation is a load.
- * @waiter The completion to finish with an error if the operation is not a load.
+ * @operation: The admin_state_code describing the operation to validate.
+ * @waiter: The completion to finish with an error if the operation is not a load.
  *
  * Return: true if the specified operation is a load.
  */
@@ -377,9 +389,10 @@ bool vdo_assert_load_operation(const struct admin_state_code *operation,
 
 /**
  * vdo_start_loading() - Initiate a load operation if the current state permits it.
- * @operation The type of load to initiate.
- * @waiter The completion to notify when the load is complete (may be NULL).
- * @initiator The vdo_admin_initiator_fn to call if the operation may begin; may be NULL.
+ * @state: The admin_state object representing the current administrative state.
+ * @operation: The type of load to initiate.
+ * @waiter: The completion to notify when the load is complete (may be NULL).
+ * @initiator: The vdo_admin_initiator_fn to call if the operation may begin; may be NULL.
  *
  * Return: true if the load was initiated, if not the waiter will be notified.
  */
@@ -393,6 +406,7 @@ bool vdo_start_loading(struct admin_state *state,
 
 /**
  * vdo_finish_loading() - Finish a load operation if one was in progress.
+ * @state: The admin_state object representing the current administrative state.
  *
  * Return: true if the state was loading; will notify the waiter if so.
  */
@@ -403,7 +417,8 @@ bool vdo_finish_loading(struct admin_state *state)
 
 /**
  * vdo_finish_loading_with_result() - Finish a load operation with a status code.
- * @result The result of the load operation.
+ * @state: The admin_state object representing the current administrative state.
+ * @result: The result of the load operation.
  *
  * Return: true if the state was loading; will notify the waiter if so.
  */
@@ -414,7 +429,8 @@ bool vdo_finish_loading_with_result(struct admin_state *state, int result)
 
 /**
  * assert_vdo_resume_operation() - Check whether an admin_state_code is a resume operation.
- * @waiter The completion to notify if the operation is not a resume operation; may be NULL.
+ * @operation: The admin_state_code to check.
+ * @waiter: The completion to notify if the operation is not a resume operation; may be NULL.
  *
  * Return: true if the code is a resume operation.
  */
@@ -427,9 +443,10 @@ static bool __must_check assert_vdo_resume_operation(const struct admin_state_co
 
 /**
  * vdo_start_resuming() - Initiate a resume operation if the current state permits it.
- * @operation The type of resume to start.
- * @waiter The completion to notify when the resume is complete (may be NULL).
- * @initiator The vdo_admin_initiator_fn to call if the operation may begin; may be NULL.
+ * @state: The admin_state object representing the current administrative state.
+ * @operation: The type of resume to start.
+ * @waiter: The completion to notify when the resume is complete (may be NULL).
+ * @initiator: The vdo_admin_initiator_fn to call if the operation may begin; may be NULL.
  *
  * Return: true if the resume was initiated, if not the waiter will be notified.
  */
@@ -443,6 +460,7 @@ bool vdo_start_resuming(struct admin_state *state,
 
 /**
  * vdo_finish_resuming() - Finish a resume operation if one was in progress.
+ * @state: The admin state object representing the current administrative state.
  *
  * Return: true if the state was resuming; will notify the waiter if so.
  */
@@ -453,7 +471,8 @@ bool vdo_finish_resuming(struct admin_state *state)
 
 /**
  * vdo_finish_resuming_with_result() - Finish a resume operation with a status code.
- * @result The result of the resume operation.
+ * @state: The admin_state object representing the current administrative state.
+ * @result: The result of the resume operation.
  *
  * Return: true if the state was resuming; will notify the waiter if so.
  */
@@ -464,6 +483,7 @@ bool vdo_finish_resuming_with_result(struct admin_state *state, int result)
 
 /**
  * vdo_resume_if_quiescent() - Change the state to normal operation if the current state is
+ * @state: The admins_state object representing the current administrative state.
  *                             quiescent.
  *
  * Return: VDO_SUCCESS if the state resumed, VDO_INVALID_ADMIN_STATE otherwise.
@@ -479,6 +499,8 @@ int vdo_resume_if_quiescent(struct admin_state *state)
 
 /**
  * vdo_start_operation() - Attempt to start an operation.
+ * @state: The admin_state object representing the current administrative state.
+ * @operation: The administrative state code representing the operation to start.
  *
  * Return: VDO_SUCCESS if the operation was started, VDO_INVALID_ADMIN_STATE if not
  */
@@ -490,8 +512,10 @@ int vdo_start_operation(struct admin_state *state,
 
 /**
  * vdo_start_operation_with_waiter() - Attempt to start an operation.
- * @waiter the completion to notify when the operation completes or fails to start; may be NULL.
- * @initiator The vdo_admin_initiator_fn to call if the operation may begin; may be NULL.
+ * @state: The admin_state object representing the current administrative state.
+ * @operation: The administrative state code representing the operation to start.
+ * @waiter: the completion to notify when the operation completes or fails to start; may be NULL.
+ * @initiator: The vdo_admin_initiator_fn to call if the operation may begin; may be NULL.
  *
  * Return: VDO_SUCCESS if the operation was started, VDO_INVALID_ADMIN_STATE if not
  */
-- 
2.43.0

Re: [PATCH] dm: vdo: fix kernel-doc warnings in admin-state.c

[Matthew Sakai]

On 11/20/25 11:47 AM, Sunday Adelodun wrote:
> Several functions in admin-state.c were missing parameter descriptions
> leading to multiple kernel-doc warnings during build.
> 
> Update the affected comments by adding missing @state, @operation,
> @waiter, @initiator, @result, and other parameter descriptions.
> 
> No functional changes.

I'm ambivalent about some of the new comments. But there are also a lot 
more kerneldoc warnings in the dm-vdo target, and now that you've 
pointed them out I think I'll try to fix them all up myself. It may take 
me a day or two to get the patch out.

Thanks for bringing this up.
Matt

> Signed-off-by: Sunday Adelodun <adelodunolaoluwa@yahoo.com>
> ---
>   drivers/md/dm-vdo/admin-state.c | 74 ++++++++++++++++++++++-----------
>   1 file changed, 49 insertions(+), 25 deletions(-)
> 
> diff --git a/drivers/md/dm-vdo/admin-state.c b/drivers/md/dm-vdo/admin-state.c
> index 3f9dba525154..eedbe080f632 100644
> --- a/drivers/md/dm-vdo/admin-state.c
> +++ b/drivers/md/dm-vdo/admin-state.c
> @@ -187,6 +187,8 @@ static const struct admin_state_code *get_next_state(const struct admin_state *s
>   
>   /**
>    * vdo_finish_operation() - Finish the current operation.
> + * @state: The admin_state object representing the current operation.
> + * @result: The result code to pass to any waiting completion handler.
>    *
>    * Will notify the operation waiter if there is one. This method should be used for operations
>    * started with vdo_start_operation(). For operations which were started with vdo_start_draining(),
> @@ -214,8 +216,10 @@ bool vdo_finish_operation(struct admin_state *state, int result)
>   
>   /**
>    * begin_operation() - Begin an operation if it may be started given the current state.
> - * @waiter A completion to notify when the operation is complete; may be NULL.
> - * @initiator The vdo_admin_initiator_fn to call if the operation may begin; may be NULL.
> + * @state: The admin_state object representing the current administrative state.
> + * @operation: The state code describing the operation to begin.
> + * @waiter: A completion to notify when the operation is complete; may be NULL.
> + * @initiator: The vdo_admin_initiator_fn to call if the operation may begin; may be NULL.
>    *
>    * Return: VDO_SUCCESS or an error.
>    */
> @@ -259,8 +263,10 @@ static int __must_check begin_operation(struct admin_state *state,
>   
>   /**
>    * start_operation() - Start an operation if it may be started given the current state.
> - * @waiter     A completion to notify when the operation is complete.
> - * @initiator The vdo_admin_initiator_fn to call if the operation may begin; may be NULL.
> + * @state: The admin_state object representing the current administrative state.
> + * @operation: The state code describing the operation to begin.
> + * @waiter:     A completion to notify when the operation is complete.
> + * @initiator: The vdo_admin_initiator_fn to call if the operation may begin; may be NULL.
>    *
>    * Return: true if the operation was started.
>    */
> @@ -274,10 +280,10 @@ static inline bool __must_check start_operation(struct admin_state *state,
>   
>   /**
>    * check_code() - Check the result of a state validation.
> - * @valid true if the code is of an appropriate type.
> - * @code The code which failed to be of the correct type.
> - * @what What the code failed to be, for logging.
> - * @waiter The completion to notify of the error; may be NULL.
> + * @valid: true if the code is of an appropriate type.
> + * @code: The code which failed to be of the correct type.
> + * @what: What the code failed to be, for logging.
> + * @waiter: The completion to notify of the error; may be NULL.
>    *
>    * If the result failed, log an invalid state error and, if there is a waiter, notify it.
>    *
> @@ -301,7 +307,8 @@ static bool check_code(bool valid, const struct admin_state_code *code, const ch
>   
>   /**
>    * assert_vdo_drain_operation() - Check that an operation is a drain.
> - * @waiter The completion to finish with an error if the operation is not a drain.
> + * @operation: The drain operation type to check.
> + * @waiter: The completion to finish with an error if the operation is not a drain.
>    *
>    * Return: true if the specified operation is a drain.
>    */
> @@ -313,11 +320,12 @@ static bool __must_check assert_vdo_drain_operation(const struct admin_state_cod
>   
>   /**
>    * vdo_start_draining() - Initiate a drain operation if the current state permits it.
> - * @operation The type of drain to initiate.
> - * @waiter The completion to notify when the drain is complete.
> - * @initiator The vdo_admin_initiator_fn to call if the operation may begin; may be NULL.
> + * @state: The admin_state object representing the current administrative state.
> + * @operation: The type of drain to initiate.
> + * @waiter: The completion to notify when the drain is complete.
> + * @initiator: The vdo_admin_initiator_fn to call if the operation may begin; may be NULL.
>    *
> - * Return: true if the drain was initiated, if not the waiter will be notified.
> + * Return: true if the drain was initiated; otherwise false, with the waiter notified.
>    */
>   bool vdo_start_draining(struct admin_state *state,
>   			const struct admin_state_code *operation,
> @@ -345,6 +353,7 @@ bool vdo_start_draining(struct admin_state *state,
>   
>   /**
>    * vdo_finish_draining() - Finish a drain operation if one was in progress.
> + * @state: The admin_state object representing the current administrative state.
>    *
>    * Return: true if the state was draining; will notify the waiter if so.
>    */
> @@ -355,6 +364,8 @@ bool vdo_finish_draining(struct admin_state *state)
>   
>   /**
>    * vdo_finish_draining_with_result() - Finish a drain operation with a status code.
> + * @state: The admin_state object representing the current administrative state.
> + * @result: The result code to return to the waiting completion.
>    *
>    * Return: true if the state was draining; will notify the waiter if so.
>    */
> @@ -365,7 +376,8 @@ bool vdo_finish_draining_with_result(struct admin_state *state, int result)
>   
>   /**
>    * vdo_assert_load_operation() - Check that an operation is a load.
> - * @waiter The completion to finish with an error if the operation is not a load.
> + * @operation: The admin_state_code describing the operation to validate.
> + * @waiter: The completion to finish with an error if the operation is not a load.
>    *
>    * Return: true if the specified operation is a load.
>    */
> @@ -377,9 +389,10 @@ bool vdo_assert_load_operation(const struct admin_state_code *operation,
>   
>   /**
>    * vdo_start_loading() - Initiate a load operation if the current state permits it.
> - * @operation The type of load to initiate.
> - * @waiter The completion to notify when the load is complete (may be NULL).
> - * @initiator The vdo_admin_initiator_fn to call if the operation may begin; may be NULL.
> + * @state: The admin_state object representing the current administrative state.
> + * @operation: The type of load to initiate.
> + * @waiter: The completion to notify when the load is complete (may be NULL).
> + * @initiator: The vdo_admin_initiator_fn to call if the operation may begin; may be NULL.
>    *
>    * Return: true if the load was initiated, if not the waiter will be notified.
>    */
> @@ -393,6 +406,7 @@ bool vdo_start_loading(struct admin_state *state,
>   
>   /**
>    * vdo_finish_loading() - Finish a load operation if one was in progress.
> + * @state: The admin_state object representing the current administrative state.
>    *
>    * Return: true if the state was loading; will notify the waiter if so.
>    */
> @@ -403,7 +417,8 @@ bool vdo_finish_loading(struct admin_state *state)
>   
>   /**
>    * vdo_finish_loading_with_result() - Finish a load operation with a status code.
> - * @result The result of the load operation.
> + * @state: The admin_state object representing the current administrative state.
> + * @result: The result of the load operation.
>    *
>    * Return: true if the state was loading; will notify the waiter if so.
>    */
> @@ -414,7 +429,8 @@ bool vdo_finish_loading_with_result(struct admin_state *state, int result)
>   
>   /**
>    * assert_vdo_resume_operation() - Check whether an admin_state_code is a resume operation.
> - * @waiter The completion to notify if the operation is not a resume operation; may be NULL.
> + * @operation: The admin_state_code to check.
> + * @waiter: The completion to notify if the operation is not a resume operation; may be NULL.
>    *
>    * Return: true if the code is a resume operation.
>    */
> @@ -427,9 +443,10 @@ static bool __must_check assert_vdo_resume_operation(const struct admin_state_co
>   
>   /**
>    * vdo_start_resuming() - Initiate a resume operation if the current state permits it.
> - * @operation The type of resume to start.
> - * @waiter The completion to notify when the resume is complete (may be NULL).
> - * @initiator The vdo_admin_initiator_fn to call if the operation may begin; may be NULL.
> + * @state: The admin_state object representing the current administrative state.
> + * @operation: The type of resume to start.
> + * @waiter: The completion to notify when the resume is complete (may be NULL).
> + * @initiator: The vdo_admin_initiator_fn to call if the operation may begin; may be NULL.
>    *
>    * Return: true if the resume was initiated, if not the waiter will be notified.
>    */
> @@ -443,6 +460,7 @@ bool vdo_start_resuming(struct admin_state *state,
>   
>   /**
>    * vdo_finish_resuming() - Finish a resume operation if one was in progress.
> + * @state: The admin state object representing the current administrative state.
>    *
>    * Return: true if the state was resuming; will notify the waiter if so.
>    */
> @@ -453,7 +471,8 @@ bool vdo_finish_resuming(struct admin_state *state)
>   
>   /**
>    * vdo_finish_resuming_with_result() - Finish a resume operation with a status code.
> - * @result The result of the resume operation.
> + * @state: The admin_state object representing the current administrative state.
> + * @result: The result of the resume operation.
>    *
>    * Return: true if the state was resuming; will notify the waiter if so.
>    */
> @@ -464,6 +483,7 @@ bool vdo_finish_resuming_with_result(struct admin_state *state, int result)
>   
>   /**
>    * vdo_resume_if_quiescent() - Change the state to normal operation if the current state is
> + * @state: The admins_state object representing the current administrative state.
>    *                             quiescent.
>    *
>    * Return: VDO_SUCCESS if the state resumed, VDO_INVALID_ADMIN_STATE otherwise.
> @@ -479,6 +499,8 @@ int vdo_resume_if_quiescent(struct admin_state *state)
>   
>   /**
>    * vdo_start_operation() - Attempt to start an operation.
> + * @state: The admin_state object representing the current administrative state.
> + * @operation: The administrative state code representing the operation to start.
>    *
>    * Return: VDO_SUCCESS if the operation was started, VDO_INVALID_ADMIN_STATE if not
>    */
> @@ -490,8 +512,10 @@ int vdo_start_operation(struct admin_state *state,
>   
>   /**
>    * vdo_start_operation_with_waiter() - Attempt to start an operation.
> - * @waiter the completion to notify when the operation completes or fails to start; may be NULL.
> - * @initiator The vdo_admin_initiator_fn to call if the operation may begin; may be NULL.
> + * @state: The admin_state object representing the current administrative state.
> + * @operation: The administrative state code representing the operation to start.
> + * @waiter: the completion to notify when the operation completes or fails to start; may be NULL.
> + * @initiator: The vdo_admin_initiator_fn to call if the operation may begin; may be NULL.
>    *
>    * Return: VDO_SUCCESS if the operation was started, VDO_INVALID_ADMIN_STATE if not
>    */

Re: [PATCH] dm: vdo: fix kernel-doc warnings in admin-state.c

[Sunday Adelodun]

On 11/21/25 03:31, Matthew Sakai wrote:
> On 11/20/25 11:47 AM, Sunday Adelodun wrote:
>> Several functions in admin-state.c were missing parameter descriptions
>> leading to multiple kernel-doc warnings during build.
>>
>> Update the affected comments by adding missing @state, @operation,
>> @waiter, @initiator, @result, and other parameter descriptions.
>>
>> No functional changes.
>
> I'm ambivalent about some of the new comments. But there are also a 
> lot more kerneldoc warnings in the dm-vdo target, and now that you've 
> pointed them out I think I'll try to fix them all up myself. It may 
> take me a day or two to get the patch out.
>
> Thanks for bringing this up.
> Matt
I saw all the kerneldoc warnings in dm-vdo but wanted to get your 
feedback on one first.
But since you said you would work on them, I will not bother again.

You are welcome.
>
>> Signed-off-by: Sunday Adelodun <adelodunolaoluwa@yahoo.com>
>> ---
>>   drivers/md/dm-vdo/admin-state.c | 74 ++++++++++++++++++++++-----------
>>   1 file changed, 49 insertions(+), 25 deletions(-)
>>
>> diff --git a/drivers/md/dm-vdo/admin-state.c 
>> b/drivers/md/dm-vdo/admin-state.c
>> index 3f9dba525154..eedbe080f632 100644
>> --- a/drivers/md/dm-vdo/admin-state.c
>> +++ b/drivers/md/dm-vdo/admin-state.c
>> @@ -187,6 +187,8 @@ static const struct admin_state_code 
>> *get_next_state(const struct admin_state *s
>>     /**
>>    * vdo_finish_operation() - Finish the current operation.
>> + * @state: The admin_state object representing the current operation.
>> + * @result: The result code to pass to any waiting completion handler.
>>    *
>>    * Will notify the operation waiter if there is one. This method 
>> should be used for operations
>>    * started with vdo_start_operation(). For operations which were 
>> started with vdo_start_draining(),
>> @@ -214,8 +216,10 @@ bool vdo_finish_operation(struct admin_state 
>> *state, int result)
>>     /**
>>    * begin_operation() - Begin an operation if it may be started 
>> given the current state.
>> - * @waiter A completion to notify when the operation is complete; 
>> may be NULL.
>> - * @initiator The vdo_admin_initiator_fn to call if the operation 
>> may begin; may be NULL.
>> + * @state: The admin_state object representing the current 
>> administrative state.
>> + * @operation: The state code describing the operation to begin.
>> + * @waiter: A completion to notify when the operation is complete; 
>> may be NULL.
>> + * @initiator: The vdo_admin_initiator_fn to call if the operation 
>> may begin; may be NULL.
>>    *
>>    * Return: VDO_SUCCESS or an error.
>>    */
>> @@ -259,8 +263,10 @@ static int __must_check begin_operation(struct 
>> admin_state *state,
>>     /**
>>    * start_operation() - Start an operation if it may be started 
>> given the current state.
>> - * @waiter     A completion to notify when the operation is complete.
>> - * @initiator The vdo_admin_initiator_fn to call if the operation 
>> may begin; may be NULL.
>> + * @state: The admin_state object representing the current 
>> administrative state.
>> + * @operation: The state code describing the operation to begin.
>> + * @waiter:     A completion to notify when the operation is complete.
>> + * @initiator: The vdo_admin_initiator_fn to call if the operation 
>> may begin; may be NULL.
>>    *
>>    * Return: true if the operation was started.
>>    */
>> @@ -274,10 +280,10 @@ static inline bool __must_check 
>> start_operation(struct admin_state *state,
>>     /**
>>    * check_code() - Check the result of a state validation.
>> - * @valid true if the code is of an appropriate type.
>> - * @code The code which failed to be of the correct type.
>> - * @what What the code failed to be, for logging.
>> - * @waiter The completion to notify of the error; may be NULL.
>> + * @valid: true if the code is of an appropriate type.
>> + * @code: The code which failed to be of the correct type.
>> + * @what: What the code failed to be, for logging.
>> + * @waiter: The completion to notify of the error; may be NULL.
>>    *
>>    * If the result failed, log an invalid state error and, if there 
>> is a waiter, notify it.
>>    *
>> @@ -301,7 +307,8 @@ static bool check_code(bool valid, const struct 
>> admin_state_code *code, const ch
>>     /**
>>    * assert_vdo_drain_operation() - Check that an operation is a drain.
>> - * @waiter The completion to finish with an error if the operation 
>> is not a drain.
>> + * @operation: The drain operation type to check.
>> + * @waiter: The completion to finish with an error if the operation 
>> is not a drain.
>>    *
>>    * Return: true if the specified operation is a drain.
>>    */
>> @@ -313,11 +320,12 @@ static bool __must_check 
>> assert_vdo_drain_operation(const struct admin_state_cod
>>     /**
>>    * vdo_start_draining() - Initiate a drain operation if the current 
>> state permits it.
>> - * @operation The type of drain to initiate.
>> - * @waiter The completion to notify when the drain is complete.
>> - * @initiator The vdo_admin_initiator_fn to call if the operation 
>> may begin; may be NULL.
>> + * @state: The admin_state object representing the current 
>> administrative state.
>> + * @operation: The type of drain to initiate.
>> + * @waiter: The completion to notify when the drain is complete.
>> + * @initiator: The vdo_admin_initiator_fn to call if the operation 
>> may begin; may be NULL.
>>    *
>> - * Return: true if the drain was initiated, if not the waiter will 
>> be notified.
>> + * Return: true if the drain was initiated; otherwise false, with 
>> the waiter notified.
>>    */
>>   bool vdo_start_draining(struct admin_state *state,
>>               const struct admin_state_code *operation,
>> @@ -345,6 +353,7 @@ bool vdo_start_draining(struct admin_state *state,
>>     /**
>>    * vdo_finish_draining() - Finish a drain operation if one was in 
>> progress.
>> + * @state: The admin_state object representing the current 
>> administrative state.
>>    *
>>    * Return: true if the state was draining; will notify the waiter 
>> if so.
>>    */
>> @@ -355,6 +364,8 @@ bool vdo_finish_draining(struct admin_state *state)
>>     /**
>>    * vdo_finish_draining_with_result() - Finish a drain operation 
>> with a status code.
>> + * @state: The admin_state object representing the current 
>> administrative state.
>> + * @result: The result code to return to the waiting completion.
>>    *
>>    * Return: true if the state was draining; will notify the waiter 
>> if so.
>>    */
>> @@ -365,7 +376,8 @@ bool vdo_finish_draining_with_result(struct 
>> admin_state *state, int result)
>>     /**
>>    * vdo_assert_load_operation() - Check that an operation is a load.
>> - * @waiter The completion to finish with an error if the operation 
>> is not a load.
>> + * @operation: The admin_state_code describing the operation to 
>> validate.
>> + * @waiter: The completion to finish with an error if the operation 
>> is not a load.
>>    *
>>    * Return: true if the specified operation is a load.
>>    */
>> @@ -377,9 +389,10 @@ bool vdo_assert_load_operation(const struct 
>> admin_state_code *operation,
>>     /**
>>    * vdo_start_loading() - Initiate a load operation if the current 
>> state permits it.
>> - * @operation The type of load to initiate.
>> - * @waiter The completion to notify when the load is complete (may 
>> be NULL).
>> - * @initiator The vdo_admin_initiator_fn to call if the operation 
>> may begin; may be NULL.
>> + * @state: The admin_state object representing the current 
>> administrative state.
>> + * @operation: The type of load to initiate.
>> + * @waiter: The completion to notify when the load is complete (may 
>> be NULL).
>> + * @initiator: The vdo_admin_initiator_fn to call if the operation 
>> may begin; may be NULL.
>>    *
>>    * Return: true if the load was initiated, if not the waiter will 
>> be notified.
>>    */
>> @@ -393,6 +406,7 @@ bool vdo_start_loading(struct admin_state *state,
>>     /**
>>    * vdo_finish_loading() - Finish a load operation if one was in 
>> progress.
>> + * @state: The admin_state object representing the current 
>> administrative state.
>>    *
>>    * Return: true if the state was loading; will notify the waiter if 
>> so.
>>    */
>> @@ -403,7 +417,8 @@ bool vdo_finish_loading(struct admin_state *state)
>>     /**
>>    * vdo_finish_loading_with_result() - Finish a load operation with 
>> a status code.
>> - * @result The result of the load operation.
>> + * @state: The admin_state object representing the current 
>> administrative state.
>> + * @result: The result of the load operation.
>>    *
>>    * Return: true if the state was loading; will notify the waiter if 
>> so.
>>    */
>> @@ -414,7 +429,8 @@ bool vdo_finish_loading_with_result(struct 
>> admin_state *state, int result)
>>     /**
>>    * assert_vdo_resume_operation() - Check whether an 
>> admin_state_code is a resume operation.
>> - * @waiter The completion to notify if the operation is not a resume 
>> operation; may be NULL.
>> + * @operation: The admin_state_code to check.
>> + * @waiter: The completion to notify if the operation is not a 
>> resume operation; may be NULL.
>>    *
>>    * Return: true if the code is a resume operation.
>>    */
>> @@ -427,9 +443,10 @@ static bool __must_check 
>> assert_vdo_resume_operation(const struct admin_state_co
>>     /**
>>    * vdo_start_resuming() - Initiate a resume operation if the 
>> current state permits it.
>> - * @operation The type of resume to start.
>> - * @waiter The completion to notify when the resume is complete (may 
>> be NULL).
>> - * @initiator The vdo_admin_initiator_fn to call if the operation 
>> may begin; may be NULL.
>> + * @state: The admin_state object representing the current 
>> administrative state.
>> + * @operation: The type of resume to start.
>> + * @waiter: The completion to notify when the resume is complete 
>> (may be NULL).
>> + * @initiator: The vdo_admin_initiator_fn to call if the operation 
>> may begin; may be NULL.
>>    *
>>    * Return: true if the resume was initiated, if not the waiter will 
>> be notified.
>>    */
>> @@ -443,6 +460,7 @@ bool vdo_start_resuming(struct admin_state *state,
>>     /**
>>    * vdo_finish_resuming() - Finish a resume operation if one was in 
>> progress.
>> + * @state: The admin state object representing the current 
>> administrative state.
>>    *
>>    * Return: true if the state was resuming; will notify the waiter 
>> if so.
>>    */
>> @@ -453,7 +471,8 @@ bool vdo_finish_resuming(struct admin_state *state)
>>     /**
>>    * vdo_finish_resuming_with_result() - Finish a resume operation 
>> with a status code.
>> - * @result The result of the resume operation.
>> + * @state: The admin_state object representing the current 
>> administrative state.
>> + * @result: The result of the resume operation.
>>    *
>>    * Return: true if the state was resuming; will notify the waiter 
>> if so.
>>    */
>> @@ -464,6 +483,7 @@ bool vdo_finish_resuming_with_result(struct 
>> admin_state *state, int result)
>>     /**
>>    * vdo_resume_if_quiescent() - Change the state to normal operation 
>> if the current state is
>> + * @state: The admins_state object representing the current 
>> administrative state.
>>    *                             quiescent.
>>    *
>>    * Return: VDO_SUCCESS if the state resumed, 
>> VDO_INVALID_ADMIN_STATE otherwise.
>> @@ -479,6 +499,8 @@ int vdo_resume_if_quiescent(struct admin_state 
>> *state)
>>     /**
>>    * vdo_start_operation() - Attempt to start an operation.
>> + * @state: The admin_state object representing the current 
>> administrative state.
>> + * @operation: The administrative state code representing the 
>> operation to start.
>>    *
>>    * Return: VDO_SUCCESS if the operation was started, 
>> VDO_INVALID_ADMIN_STATE if not
>>    */
>> @@ -490,8 +512,10 @@ int vdo_start_operation(struct admin_state *state,
>>     /**
>>    * vdo_start_operation_with_waiter() - Attempt to start an operation.
>> - * @waiter the completion to notify when the operation completes or 
>> fails to start; may be NULL.
>> - * @initiator The vdo_admin_initiator_fn to call if the operation 
>> may begin; may be NULL.
>> + * @state: The admin_state object representing the current 
>> administrative state.
>> + * @operation: The administrative state code representing the 
>> operation to start.
>> + * @waiter: the completion to notify when the operation completes or 
>> fails to start; may be NULL.
>> + * @initiator: The vdo_admin_initiator_fn to call if the operation 
>> may begin; may be NULL.
>>    *
>>    * Return: VDO_SUCCESS if the operation was started, 
>> VDO_INVALID_ADMIN_STATE if not
>>    */
>