| Message ID | 1519764591-27456-2-git-send-email-longman@redhat.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
On Tue, Feb 27, 2018 at 03:49:47PM -0500, Waiman Long wrote: > +/** > + * DOC: do_proc_dointvec_minmax_conv_param > + * > + * The do_proc_dointvec_minmax_conv_param structure provides the > + * minimum and maximum values for doing range checking for those sysctl > + * parameters that use the proc_dointvec_minmax() handler. The error > + * code -EINVAL will be returned if the range check fails. > + * > + * min: ptr to minimum allowable value > + * max: ptr to maximum allowable value > + */ This isn't how to document a struct; see Documentation/doc-guide/kernel-doc.rst /** * struct do_proc_dointvec_minmax_conv_param - Range checking for sysctls * @min: Pointer to minimum allowable value. * @max: Pointer to maximum allowable value. * * Provides the minimum and maximum values allowed for a parameter. A * pointer to this structure should be passed to proc_dointvec_minmax(). */ Also, it's inappropriate to document the return value from proc_dointvec_minmax() here; that should be in the kernel-doc for the function.
On 02/27/2018 04:10 PM, Matthew Wilcox wrote: > On Tue, Feb 27, 2018 at 03:49:47PM -0500, Waiman Long wrote: >> +/** >> + * DOC: do_proc_dointvec_minmax_conv_param >> + * >> + * The do_proc_dointvec_minmax_conv_param structure provides the >> + * minimum and maximum values for doing range checking for those sysctl >> + * parameters that use the proc_dointvec_minmax() handler. The error >> + * code -EINVAL will be returned if the range check fails. >> + * >> + * min: ptr to minimum allowable value >> + * max: ptr to maximum allowable value >> + */ > This isn't how to document a struct; see Documentation/doc-guide/kernel-doc.rst > > /** > * struct do_proc_dointvec_minmax_conv_param - Range checking for sysctls > * @min: Pointer to minimum allowable value. > * @max: Pointer to maximum allowable value. > * > * Provides the minimum and maximum values allowed for a parameter. A > * pointer to this structure should be passed to proc_dointvec_minmax(). > */ > > Also, it's inappropriate to document the return value from > proc_dointvec_minmax() here; that should be in the kernel-doc for the > function. > Thanks for the advice. I will change the comments in the v3 patch. -Longman
diff --git a/kernel/sysctl.c b/kernel/sysctl.c index f98f28c..52b647a 100644 --- a/kernel/sysctl.c +++ b/kernel/sysctl.c @@ -2500,6 +2500,17 @@ static int proc_dointvec_minmax_sysadmin(struct ctl_table *table, int write, } #endif +/** + * DOC: do_proc_dointvec_minmax_conv_param + * + * The do_proc_dointvec_minmax_conv_param structure provides the + * minimum and maximum values for doing range checking for those sysctl + * parameters that use the proc_dointvec_minmax() handler. The error + * code -EINVAL will be returned if the range check fails. + * + * min: ptr to minimum allowable value + * max: ptr to maximum allowable value + */ struct do_proc_dointvec_minmax_conv_param { int *min; int *max; @@ -2556,6 +2567,17 @@ int proc_dointvec_minmax(struct ctl_table *table, int write, do_proc_dointvec_minmax_conv, ¶m); } +/** + * DOC: do_proc_douintvec_minmax_conv_param + * + * The do_proc_dointvec_minmax_conv_param structure provides the + * minimum and maximum values for doing range checking for those sysctl + * parameters that use the proc_douintvec_minmax() handler. The error + * code -ERANGE will be returned if the range check fails. + * + * min: ptr to minimum allowable value + * max: ptr to maximum allowable value + */ struct do_proc_douintvec_minmax_conv_param { unsigned int *min; unsigned int *max;
Kdoc comments are added to the do_proc_dointvec_minmax_conv_param and do_proc_douintvec_minmax_conv_param structures thare are used internally for range checking. Signed-off-by: Waiman Long <longman@redhat.com> --- kernel/sysctl.c | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+)