* [PATCH] dm: vdo: fix kernel-doc warnings in admin-state.c [not found] <20251120164734.7187-1-adelodunolaoluwa.ref@yahoo.com> @ 2025-11-20 16:47 ` Sunday Adelodun 2025-11-21 2:31 ` Matthew Sakai 0 siblings, 1 reply; 3+ messages in thread From: Sunday Adelodun @ 2025-11-20 16:47 UTC (permalink / raw) To: msakai Cc: dm-devel, linux-kernel, skhan, david.hunter.linux, linux-kernel-mentees, 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 ^ permalink raw reply related [flat|nested] 3+ messages in thread
* Re: [PATCH] dm: vdo: fix kernel-doc warnings in admin-state.c 2025-11-20 16:47 ` [PATCH] dm: vdo: fix kernel-doc warnings in admin-state.c Sunday Adelodun @ 2025-11-21 2:31 ` Matthew Sakai 2025-11-21 8:20 ` Sunday Adelodun 0 siblings, 1 reply; 3+ messages in thread From: Matthew Sakai @ 2025-11-21 2:31 UTC (permalink / raw) To: Sunday Adelodun Cc: dm-devel, linux-kernel, skhan, david.hunter.linux, linux-kernel-mentees 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 > */ ^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [PATCH] dm: vdo: fix kernel-doc warnings in admin-state.c 2025-11-21 2:31 ` Matthew Sakai @ 2025-11-21 8:20 ` Sunday Adelodun 0 siblings, 0 replies; 3+ messages in thread From: Sunday Adelodun @ 2025-11-21 8:20 UTC (permalink / raw) To: Matthew Sakai Cc: dm-devel, linux-kernel, skhan, david.hunter.linux, linux-kernel-mentees 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 >> */ > ^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2025-11-21 8:21 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
[not found] <20251120164734.7187-1-adelodunolaoluwa.ref@yahoo.com>
2025-11-20 16:47 ` [PATCH] dm: vdo: fix kernel-doc warnings in admin-state.c Sunday Adelodun
2025-11-21 2:31 ` Matthew Sakai
2025-11-21 8:20 ` Sunday Adelodun
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox