[PATCH -next 00/11] Fix kernel-doc warnings in apparmor

[PATCH -next 00/11] Fix kernel-doc warnings in apparmor

[Gaosheng Cui]

Fix kernel-doc warnings in apparmor, thanks very much!

Gaosheng Cui (11):
  apparmor: Fix kernel-doc warnings in apparmor/audit.c
  apparmor: Fix kernel-doc warnings in apparmor/capability.c
  apparmor: Fix kernel-doc warnings in apparmor/domain.c
  apparmor: Fix kernel-doc warnings in apparmor/file.c
  apparmor: Fix kernel-doc warnings in apparmor/label.c
  apparmor: Fix kernel-doc warnings in apparmor/lib.c
  apparmor: Fix kernel-doc warnings in apparmor/match.c
  apparmor: Fix kernel-doc warnings in apparmor/resource.c
  apparmor: Fix kernel-doc warnings in apparmor/policy_unpack.c
  apparmor: Fix kernel-doc warnings in apparmor/policy_compat.c
  apparmor: Fix kernel-doc warnings in apparmor/policy.c

 security/apparmor/audit.c         |  1 +
 security/apparmor/capability.c    |  4 ++--
 security/apparmor/domain.c        | 10 ++++++----
 security/apparmor/file.c          |  6 +++---
 security/apparmor/label.c         | 20 +++++++++++---------
 security/apparmor/lib.c           |  4 ++--
 security/apparmor/match.c         |  4 ++--
 security/apparmor/policy.c        | 17 ++++++++++-------
 security/apparmor/policy_compat.c |  1 +
 security/apparmor/policy_unpack.c |  2 +-
 security/apparmor/resource.c      |  8 ++++----
 11 files changed, 43 insertions(+), 34 deletions(-)

-- 
2.25.1

[PATCH -next 01/11] apparmor: Fix kernel-doc warnings in apparmor/audit.c

[Gaosheng Cui]

Fix kernel-doc warnings:

security/apparmor/audit.c:150: warning: Function parameter or
member 'type' not described in 'aa_audit_msg'

Signed-off-by: Gaosheng Cui <cuigaosheng1@huawei.com>
---
 security/apparmor/audit.c | 1 +
 1 file changed, 1 insertion(+)

diff --git a/security/apparmor/audit.c b/security/apparmor/audit.c
index 5a7978aa4b19..a3db0f8bd4f8 100644
--- a/security/apparmor/audit.c
+++ b/security/apparmor/audit.c
@@ -142,6 +142,7 @@ static void audit_pre(struct audit_buffer *ab, void *ca)
 
 /**
  * aa_audit_msg - Log a message to the audit subsystem
+ * @type: audit type for the message
  * @sa: audit event structure (NOT NULL)
  * @cb: optional callback fn for type specific fields (MAYBE NULL)
  */
-- 
2.25.1

[PATCH -next 02/11] apparmor: Fix kernel-doc warnings in apparmor/capability.c

[Gaosheng Cui]

Fix kernel-doc warnings:

security/apparmor/capability.c:45: warning: Function parameter
or member 'ab' not described in 'audit_cb'
security/apparmor/capability.c:45: warning: Function parameter
or member 'va' not described in 'audit_cb'

Signed-off-by: Gaosheng Cui <cuigaosheng1@huawei.com>
---
 security/apparmor/capability.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/security/apparmor/capability.c b/security/apparmor/capability.c
index 326a51838ef2..8ebf0fcb796c 100644
--- a/security/apparmor/capability.c
+++ b/security/apparmor/capability.c
@@ -38,8 +38,8 @@ static DEFINE_PER_CPU(struct audit_cache, audit_cache);
 
 /**
  * audit_cb - call back for capability components of audit struct
- * @ab - audit buffer   (NOT NULL)
- * @va - audit struct to audit data from  (NOT NULL)
+ * @ab: audit buffer   (NOT NULL)
+ * @va: audit struct to audit data from  (NOT NULL)
  */
 static void audit_cb(struct audit_buffer *ab, void *va)
 {
-- 
2.25.1

[PATCH -next 03/11] apparmor: Fix kernel-doc warnings in apparmor/domain.c

[Gaosheng Cui]

Fix kernel-doc warnings:

security/apparmor/domain.c:279: warning: Function parameter or
member 'perms' not described in 'change_profile_perms'
security/apparmor/domain.c:380: warning: Function parameter or
member 'bprm' not described in 'find_attach'
security/apparmor/domain.c:380: warning: Function parameter or
member 'head' not described in 'find_attach'
security/apparmor/domain.c:380: warning: Function parameter or
member 'info' not described in 'find_attach'
security/apparmor/domain.c:380: warning: Function parameter or
member 'name' not described in 'find_attach'
security/apparmor/domain.c:558: warning: Function parameter or
member 'info' not described in 'x_to_label'

Signed-off-by: Gaosheng Cui <cuigaosheng1@huawei.com>
---
 security/apparmor/domain.c | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/security/apparmor/domain.c b/security/apparmor/domain.c
index 68598557aef5..7f81502019da 100644
--- a/security/apparmor/domain.c
+++ b/security/apparmor/domain.c
@@ -265,6 +265,7 @@ static int label_match(struct aa_profile *profile, struct aa_label *label,
  * @stack: whether this is a stacking request
  * @request: requested perms
  * @start: state to start matching in
+ * @perms: Returns computed perms (NOT NULL)
  *
  *
  * Returns: permission set
@@ -359,11 +360,11 @@ static int aa_xattrs_match(const struct linux_binprm *bprm,
 
 /**
  * find_attach - do attachment search for unconfined processes
- * @bprm - binprm structure of transitioning task
+ * @bprm: binprm structure of transitioning task
  * @ns: the current namespace  (NOT NULL)
- * @head - profile list to walk  (NOT NULL)
- * @name - to match against  (NOT NULL)
- * @info - info message if there was an error (NOT NULL)
+ * @head: profile list to walk  (NOT NULL)
+ * @name: to match against  (NOT NULL)
+ * @info: info message if there was an error (NOT NULL)
  *
  * Do a linear search on the profiles in the list.  There is a matching
  * preference where an exact match is preferred over a name which uses
@@ -545,6 +546,7 @@ struct aa_label *x_table_lookup(struct aa_profile *profile, u32 xindex,
  * @name: name to lookup (NOT NULL)
  * @xindex: index into x transition table
  * @lookupname: returns: name used in lookup if one was specified (NOT NULL)
+ * @info: info message if there was an error (NOT NULL)
  *
  * find label for a transition index
  *
-- 
2.25.1

[PATCH -next 04/11] apparmor: Fix kernel-doc warnings in apparmor/file.c

[Gaosheng Cui]

Fix kernel-doc warnings:

security/apparmor/file.c:177: warning: Excess function parameter
'dfa' description in 'aa_lookup_fperms'
security/apparmor/file.c:177: warning: Function parameter or member
'file_rules' not described in 'aa_lookup_fperms'
security/apparmor/file.c:202: warning: Excess function parameter
'dfa' description in 'aa_str_perms'
security/apparmor/file.c:202: warning: Excess function parameter
'state' description in 'aa_str_perms'
security/apparmor/file.c:202: warning: Function parameter or member
'file_rules' not described in 'aa_str_perms'
security/apparmor/file.c:202: warning: Function parameter or member
'start' not described in 'aa_str_perms'

Signed-off-by: Gaosheng Cui <cuigaosheng1@huawei.com>
---
 security/apparmor/file.c | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/security/apparmor/file.c b/security/apparmor/file.c
index 698b124e649f..c0fc5e77e889 100644
--- a/security/apparmor/file.c
+++ b/security/apparmor/file.c
@@ -164,7 +164,7 @@ static int path_name(const char *op, struct aa_label *label,
 struct aa_perms default_perms = {};
 /**
  * aa_lookup_fperms - convert dfa compressed perms to internal perms
- * @dfa: dfa to lookup perms for   (NOT NULL)
+ * @file_rules: the aa_policydb to lookup perms for  (NOT NULL)
  * @state: state in dfa
  * @cond:  conditions to consider  (NOT NULL)
  *
@@ -188,8 +188,8 @@ struct aa_perms *aa_lookup_fperms(struct aa_policydb *file_rules,
 
 /**
  * aa_str_perms - find permission that match @name
- * @dfa: to match against  (MAYBE NULL)
- * @state: state to start matching in
+ * @file_rules: the aa_policydb to match against  (NOT NULL)
+ * @start: state to start matching in
  * @name: string to match against dfa  (NOT NULL)
  * @cond: conditions to consider for permission set computation  (NOT NULL)
  * @perms: Returns - the permissions found when matching @name
-- 
2.25.1

[PATCH -next 05/11] apparmor: Fix kernel-doc warnings in apparmor/label.c

[Gaosheng Cui]

Fix kernel-doc warnings:

security/apparmor/label.c:166: warning: Excess function parameter
'n' description in 'vec_cmp'
security/apparmor/label.c:166: warning: Excess function parameter
'vec' description in 'vec_cmp'
security/apparmor/label.c:166: warning: Function parameter or member
'an' not described in 'vec_cmp'
security/apparmor/label.c:166: warning: Function parameter or member
'bn' not described in 'vec_cmp'
security/apparmor/label.c:166: warning: Function parameter or member
'b' not described in 'vec_cmp'
security/apparmor/label.c:2051: warning: Function parameter or member
'label' not described in '__label_update'
security/apparmor/label.c:266: warning: Function parameter or member
'flags' not described in 'aa_vec_unique'
security/apparmor/label.c:594: warning: Excess function parameter
'l' description in '__label_remove'
security/apparmor/label.c:594: warning: Function parameter or member
'label' not described in '__label_remove'
security/apparmor/label.c:929: warning: Function parameter or member
'label' not described in 'aa_label_insert'
security/apparmor/label.c:929: warning: Function parameter or member
'ls' not described in 'aa_label_insert'
security/apparmor/label.c:1221: warning: Excess function parameter
'ls' description in 'aa_label_merge'
security/apparmor/label.c:1302: warning: Excess function parameter
'start' description in 'label_compound_match'
security/apparmor/label.c:1302: warning: Function parameter or member
'rules' not described in 'label_compound_match'
security/apparmor/label.c:1302: warning: Function parameter or member
'state' not described in 'label_compound_match'
security/apparmor/label.c:2051: warning: Function parameter or member
'label' not described in '__label_update'

Signed-off-by: Gaosheng Cui <cuigaosheng1@huawei.com>
---
 security/apparmor/label.c | 20 +++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

diff --git a/security/apparmor/label.c b/security/apparmor/label.c
index 8a2af96f4da5..ce9c39102a93 100644
--- a/security/apparmor/label.c
+++ b/security/apparmor/label.c
@@ -154,9 +154,10 @@ static int profile_cmp(struct aa_profile *a, struct aa_profile *b)
 
 /**
  * vec_cmp - label comparison for set ordering
- * @a: label to compare (NOT NULL)
- * @vec: vector of profiles to compare (NOT NULL)
- * @n: length of @vec
+ * @a: aa_profile to compare (NOT NULL)
+ * @an: length of @a
+ * @b: aa_profile to compare (NOT NULL)
+ * @bn: length of @b
  *
  * Returns: <0  if a < vec
  *          ==0 if a == vec
@@ -256,6 +257,7 @@ static inline int unique(struct aa_profile **vec, int n)
  * aa_vec_unique - canonical sort and unique a list of profiles
  * @n: number of refcounted profiles in the list (@n > 0)
  * @vec: list of profiles to sort and merge
+ * @flags: null terminator flags of @vec
  *
  * Returns: the number of duplicates eliminated == references put
  *
@@ -584,7 +586,7 @@ bool aa_label_is_unconfined_subset(struct aa_label *set, struct aa_label *sub)
 
 /**
  * __label_remove - remove @label from the label set
- * @l: label to remove
+ * @label: label to remove
  * @new: label to redirect to
  *
  * Requires: labels_set(@label)->lock write_lock
@@ -917,8 +919,8 @@ struct aa_label *aa_label_find(struct aa_label *label)
 
 /**
  * aa_label_insert - insert label @label into @ls or return existing label
- * @ls - labelset to insert @label into
- * @label - label to insert
+ * @ls: labelset to insert @label into
+ * @label: label to insert
  *
  * Requires: caller to hold a valid ref on @label
  *
@@ -1204,7 +1206,6 @@ struct aa_label *aa_label_find_merge(struct aa_label *a, struct aa_label *b)
 
 /**
  * aa_label_merge - attempt to insert new merged label of @a and @b
- * @ls: set of labels to insert label into (NOT NULL)
  * @a: label to merge with @b  (NOT NULL)
  * @b: label to merge with @a  (NOT NULL)
  * @gfp: memory allocation type
@@ -1282,8 +1283,9 @@ static inline aa_state_t match_component(struct aa_profile *profile,
 /**
  * label_compound_match - find perms for full compound label
  * @profile: profile to find perms for
+ * @rules: ruleset to search
  * @label: label to check access permissions for
- * @start: state to start match in
+ * @state: state to start match in
  * @subns: whether to do permission checks on components in a subns
  * @request: permissions to request
  * @perms: perms struct to set
@@ -2037,7 +2039,7 @@ static struct aa_label *labelset_next_stale(struct aa_labelset *ls)
 
 /**
  * __label_update - insert updated version of @label into labelset
- * @label - the label to update/replace
+ * @label: the label to update/replace
  *
  * Returns: new label that is up to date
  *     else NULL on failure
-- 
2.25.1

[PATCH -next 06/11] apparmor: Fix kernel-doc warnings in apparmor/lib.c

[Gaosheng Cui]

Fix kernel-doc warnings:

security/apparmor/lib.c:33: warning: Excess function parameter
'str' description in 'aa_free_str_table'
security/apparmor/lib.c:33: warning: Function parameter or member
't' not described in 'aa_free_str_table'
security/apparmor/lib.c:94: warning: Function parameter or
member 'n' not described in 'skipn_spaces'
security/apparmor/lib.c:390: warning: Excess function parameter
'deny' description in 'aa_check_perms'

Signed-off-by: Gaosheng Cui <cuigaosheng1@huawei.com>
---
 security/apparmor/lib.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/security/apparmor/lib.c b/security/apparmor/lib.c
index a630c951bb3b..8e1073477c09 100644
--- a/security/apparmor/lib.c
+++ b/security/apparmor/lib.c
@@ -27,7 +27,7 @@ struct aa_perms allperms = { .allow = ALL_PERMS_MASK,
 
 /**
  * aa_free_str_table - free entries str table
- * @str: the string table to free  (MAYBE NULL)
+ * @t: the string table to free  (MAYBE NULL)
  */
 void aa_free_str_table(struct aa_str_table *t)
 {
@@ -85,6 +85,7 @@ char *aa_split_fqname(char *fqname, char **ns_name)
 /**
  * skipn_spaces - Removes leading whitespace from @str.
  * @str: The string to be stripped.
+ * @n: length of str to parse, will stop at \0 if encountered before n
  *
  * Returns a pointer to the first non-whitespace character in @str.
  * if all whitespace will return NULL
@@ -371,7 +372,6 @@ int aa_profile_label_perm(struct aa_profile *profile, struct aa_profile *target,
  * @profile: profile being checked
  * @perms: perms computed for the request
  * @request: requested perms
- * @deny: Returns: explicit deny set
  * @sa: initialized audit structure (MAY BE NULL if not auditing)
  * @cb: callback fn for type specific fields (MAY BE NULL)
  *
-- 
2.25.1

[PATCH -next 07/11] apparmor: Fix kernel-doc warnings in apparmor/match.c

[Gaosheng Cui]

Fix kernel-doc warnings:

security/apparmor/match.c:148: warning: Function parameter or member
'tables' not described in 'verify_table_headers'
security/apparmor/match.c:289: warning: Excess function parameter
'kr' description in 'aa_dfa_free_kref'
security/apparmor/match.c:289: warning: Function parameter or member
'kref' not described in 'aa_dfa_free_kref'

Signed-off-by: Gaosheng Cui <cuigaosheng1@huawei.com>
---
 security/apparmor/match.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/security/apparmor/match.c b/security/apparmor/match.c
index b97ef5e1db73..7bdcca2aed7d 100644
--- a/security/apparmor/match.c
+++ b/security/apparmor/match.c
@@ -136,7 +136,7 @@ static struct table_header *unpack_table(char *blob, size_t bsize)
 
 /**
  * verify_table_headers - verify that the tables headers are as expected
- * @tables - array of dfa tables to check (NOT NULL)
+ * @tables: array of dfa tables to check (NOT NULL)
  * @flags: flags controlling what type of accept table are acceptable
  *
  * Assumes dfa has gone through the first pass verification done by unpacking
@@ -283,7 +283,7 @@ static void dfa_free(struct aa_dfa *dfa)
 
 /**
  * aa_dfa_free_kref - free aa_dfa by kref (called by aa_put_dfa)
- * @kr: kref callback for freeing of a dfa  (NOT NULL)
+ * @kref: kref callback for freeing of a dfa  (NOT NULL)
  */
 void aa_dfa_free_kref(struct kref *kref)
 {
-- 
2.25.1

[PATCH -next 08/11] apparmor: Fix kernel-doc warnings in apparmor/resource.c

[Gaosheng Cui]

Fix kernel-doc warnings:

security/apparmor/resource.c:111: warning: Function parameter or
member 'label' not described in 'aa_task_setrlimit'
security/apparmor/resource.c:111: warning: Function parameter or
member 'new_rlim' not described in 'aa_task_setrlimit'
security/apparmor/resource.c:111: warning: Function parameter or
member 'resource' not described in 'aa_task_setrlimit'
security/apparmor/resource.c:111: warning: Function parameter or
member 'task' not described in 'aa_task_setrlimit'

Signed-off-by: Gaosheng Cui <cuigaosheng1@huawei.com>
---
 security/apparmor/resource.c | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/security/apparmor/resource.c b/security/apparmor/resource.c
index e85948164896..2bebc5d9e741 100644
--- a/security/apparmor/resource.c
+++ b/security/apparmor/resource.c
@@ -97,10 +97,10 @@ static int profile_setrlimit(struct aa_profile *profile, unsigned int resource,
 
 /**
  * aa_task_setrlimit - test permission to set an rlimit
- * @label - label confining the task  (NOT NULL)
- * @task - task the resource is being set on
- * @resource - the resource being set
- * @new_rlim - the new resource limit  (NOT NULL)
+ * @label: label confining the task  (NOT NULL)
+ * @task: task the resource is being set on
+ * @resource: the resource being set
+ * @new_rlim: the new resource limit  (NOT NULL)
  *
  * Control raising the processes hard limit.
  *
-- 
2.25.1

[PATCH -next 09/11] apparmor: Fix kernel-doc warnings in apparmor/policy_unpack.c

[Gaosheng Cui]

Fix kernel-doc warnings:

security/apparmor/policy_unpack.c:1173: warning: Function parameter
or member 'table_size' not described in 'verify_dfa_accept_index'

Signed-off-by: Gaosheng Cui <cuigaosheng1@huawei.com>
---
 security/apparmor/policy_unpack.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/security/apparmor/policy_unpack.c b/security/apparmor/policy_unpack.c
index 694fb7a09962..d2d740bb5618 100644
--- a/security/apparmor/policy_unpack.c
+++ b/security/apparmor/policy_unpack.c
@@ -1167,7 +1167,7 @@ static int verify_header(struct aa_ext *e, int required, const char **ns)
 /**
  * verify_dfa_accept_index - verify accept indexes are in range of perms table
  * @dfa: the dfa to check accept indexes are in range
- * table_size: the permission table size the indexes should be within
+ * @table_size: the permission table size the indexes should be within
  */
 static bool verify_dfa_accept_index(struct aa_dfa *dfa, int table_size)
 {
-- 
2.25.1

[PATCH -next 10/11] apparmor: Fix kernel-doc warnings in apparmor/policy_compat.c

[Gaosheng Cui]

Fix kernel-doc warnings:

security/apparmor/policy_compat.c:151: warning: Function parameter
or member 'size' not described in 'compute_fperms'

Signed-off-by: Gaosheng Cui <cuigaosheng1@huawei.com>
---
 security/apparmor/policy_compat.c | 1 +
 1 file changed, 1 insertion(+)

diff --git a/security/apparmor/policy_compat.c b/security/apparmor/policy_compat.c
index 0cb02da8a319..18e4ddccf623 100644
--- a/security/apparmor/policy_compat.c
+++ b/security/apparmor/policy_compat.c
@@ -143,6 +143,7 @@ static struct aa_perms compute_fperms_other(struct aa_dfa *dfa,
  * compute_fperms - convert dfa compressed perms to internal perms and store
  *		    them so they can be retrieved later.
  * @dfa: a dfa using fperms to remap to internal permissions
+ * @size: the permission table size
  *
  * Returns: remapped perm table
  */
-- 
2.25.1

[PATCH -next 11/11] apparmor: Fix kernel-doc warnings in apparmor/policy.c

[Gaosheng Cui]

Fix kernel-doc warnings:

security/apparmor/policy.c:294: warning: Function parameter or
member 'proxy' not described in 'aa_alloc_profile'
security/apparmor/policy.c:785: warning: Function parameter or
member 'label' not described in 'aa_policy_view_capable'
security/apparmor/policy.c:785: warning: Function parameter or
member 'ns' not described in 'aa_policy_view_capable'
security/apparmor/policy.c:847: warning: Function parameter or
member 'ns' not described in 'aa_may_manage_policy'
security/apparmor/policy.c:964: warning: Function parameter or
member 'hname' not described in '__lookup_replace'
security/apparmor/policy.c:964: warning: Function parameter or
member 'info' not described in '__lookup_replace'
security/apparmor/policy.c:964: warning: Function parameter or
member 'noreplace' not described in '__lookup_replace'
security/apparmor/policy.c:964: warning: Function parameter or
member 'ns' not described in '__lookup_replace'
security/apparmor/policy.c:964: warning: Function parameter or
member 'p' not described in '__lookup_replace'

Signed-off-by: Gaosheng Cui <cuigaosheng1@huawei.com>
---
 security/apparmor/policy.c | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/security/apparmor/policy.c b/security/apparmor/policy.c
index 715fe1b66d12..4817c1b30105 100644
--- a/security/apparmor/policy.c
+++ b/security/apparmor/policy.c
@@ -285,6 +285,7 @@ void aa_free_profile(struct aa_profile *profile)
 /**
  * aa_alloc_profile - allocate, initialize and return a new profile
  * @hname: name of the profile  (NOT NULL)
+ * @proxy: proxy to use OR null if to allocate a new one
  * @gfp: allocation type
  *
  * Returns: refcount profile or NULL on failure
@@ -774,8 +775,9 @@ static int policy_ns_capable(struct aa_label *label,
 
 /**
  * aa_policy_view_capable - check if viewing policy in at @ns is allowed
- * label: label that is trying to view policy in ns
- * ns: namespace being viewed by @label (may be NULL if @label's ns)
+ * @label: label that is trying to view policy in ns
+ * @ns: namespace being viewed by @label (may be NULL if @label's ns)
+ *
  * Returns: true if viewing policy is allowed
  *
  * If @ns is NULL then the namespace being viewed is assumed to be the
@@ -839,6 +841,7 @@ bool aa_current_policy_admin_capable(struct aa_ns *ns)
 /**
  * aa_may_manage_policy - can the current task manage policy
  * @label: label to check if it can manage policy
+ * @ns: namespace being managed by @label (may be NULL if @label's ns)
  * @mask: contains the policy manipulation operation being done
  *
  * Returns: 0 if the task is allowed to manipulate policy else error
@@ -950,11 +953,11 @@ static void __replace_profile(struct aa_profile *old, struct aa_profile *new)
 
 /**
  * __lookup_replace - lookup replacement information for a profile
- * @ns - namespace the lookup occurs in
- * @hname - name of profile to lookup
- * @noreplace - true if not replacing an existing profile
- * @p - Returns: profile to be replaced
- * @info - Returns: info string on why lookup failed
+ * @ns: namespace the lookup occurs in
+ * @hname: name of profile to lookup
+ * @noreplace: true if not replacing an existing profile
+ * @p: Returns - profile to be replaced
+ * @info: Returns - info string on why lookup failed
  *
  * Returns: profile to replace (no ref) on success else ptr error
  */
-- 
2.25.1

Re: [PATCH -next 05/11] apparmor: Fix kernel-doc warnings in apparmor/label.c

[Georgia Garcia]

Hi, Gaosheng Cui

On Sun, 2023-06-25 at 09:13 +0800, Gaosheng Cui wrote:
> Fix kernel-doc warnings:
> 
> security/apparmor/label.c:166: warning: Excess function parameter
> 'n' description in 'vec_cmp'
> security/apparmor/label.c:166: warning: Excess function parameter
> 'vec' description in 'vec_cmp'
> security/apparmor/label.c:166: warning: Function parameter or member
> 'an' not described in 'vec_cmp'
> security/apparmor/label.c:166: warning: Function parameter or member
> 'bn' not described in 'vec_cmp'
> security/apparmor/label.c:166: warning: Function parameter or member
> 'b' not described in 'vec_cmp'
> security/apparmor/label.c:2051: warning: Function parameter or member
> 'label' not described in '__label_update'
> security/apparmor/label.c:266: warning: Function parameter or member
> 'flags' not described in 'aa_vec_unique'
> security/apparmor/label.c:594: warning: Excess function parameter
> 'l' description in '__label_remove'
> security/apparmor/label.c:594: warning: Function parameter or member
> 'label' not described in '__label_remove'
> security/apparmor/label.c:929: warning: Function parameter or member
> 'label' not described in 'aa_label_insert'
> security/apparmor/label.c:929: warning: Function parameter or member
> 'ls' not described in 'aa_label_insert'
> security/apparmor/label.c:1221: warning: Excess function parameter
> 'ls' description in 'aa_label_merge'
> security/apparmor/label.c:1302: warning: Excess function parameter
> 'start' description in 'label_compound_match'
> security/apparmor/label.c:1302: warning: Function parameter or member
> 'rules' not described in 'label_compound_match'
> security/apparmor/label.c:1302: warning: Function parameter or member
> 'state' not described in 'label_compound_match'
> security/apparmor/label.c:2051: warning: Function parameter or member
> 'label' not described in '__label_update'
> 
> Signed-off-by: Gaosheng Cui <cuigaosheng1@huawei.com>
> ---
>  security/apparmor/label.c | 20 +++++++++++---------
>  1 file changed, 11 insertions(+), 9 deletions(-)
> 
> diff --git a/security/apparmor/label.c b/security/apparmor/label.c
> index 8a2af96f4da5..ce9c39102a93 100644
> --- a/security/apparmor/label.c
> +++ b/security/apparmor/label.c
> @@ -154,9 +154,10 @@ static int profile_cmp(struct aa_profile *a, struct aa_profile *b)
>  
>  /**
>   * vec_cmp - label comparison for set ordering
> - * @a: label to compare (NOT NULL)
> - * @vec: vector of profiles to compare (NOT NULL)
> - * @n: length of @vec
> + * @a: aa_profile to compare (NOT NULL)
> + * @an: length of @a
> + * @b: aa_profile to compare (NOT NULL)
> + * @bn: length of @b
>   *
>   * Returns: <0  if a < vec
>   *          ==0 if a == vec

The "Returns:" part of the doc should also be changed to match the
different parameter name.

> @@ -256,6 +257,7 @@ static inline int unique(struct aa_profile **vec, int n)
>   * aa_vec_unique - canonical sort and unique a list of profiles
>   * @n: number of refcounted profiles in the list (@n > 0)
>   * @vec: list of profiles to sort and merge
> + * @flags: null terminator flags of @vec
>   *
>   * Returns: the number of duplicates eliminated == references put
>   *
> @@ -584,7 +586,7 @@ bool aa_label_is_unconfined_subset(struct aa_label *set, struct aa_label *sub)
>  
>  /**
>   * __label_remove - remove @label from the label set
> - * @l: label to remove
> + * @label: label to remove
>   * @new: label to redirect to
>   *
>   * Requires: labels_set(@label)->lock write_lock
> @@ -917,8 +919,8 @@ struct aa_label *aa_label_find(struct aa_label *label)
>  
>  /**
>   * aa_label_insert - insert label @label into @ls or return existing label
> - * @ls - labelset to insert @label into
> - * @label - label to insert
> + * @ls: labelset to insert @label into
> + * @label: label to insert
>   *
>   * Requires: caller to hold a valid ref on @label
>   *
> @@ -1204,7 +1206,6 @@ struct aa_label *aa_label_find_merge(struct aa_label *a, struct aa_label *b)
>  
>  /**
>   * aa_label_merge - attempt to insert new merged label of @a and @b
> - * @ls: set of labels to insert label into (NOT NULL)
>   * @a: label to merge with @b  (NOT NULL)
>   * @b: label to merge with @a  (NOT NULL)
>   * @gfp: memory allocation type
> @@ -1282,8 +1283,9 @@ static inline aa_state_t match_component(struct aa_profile *profile,
>  /**
>   * label_compound_match - find perms for full compound label
>   * @profile: profile to find perms for
> + * @rules: ruleset to search
>   * @label: label to check access permissions for
> - * @start: state to start match in
> + * @state: state to start match in
>   * @subns: whether to do permission checks on components in a subns
>   * @request: permissions to request
>   * @perms: perms struct to set
> @@ -2037,7 +2039,7 @@ static struct aa_label *labelset_next_stale(struct aa_labelset *ls)
>  
>  /**
>   * __label_update - insert updated version of @label into labelset
> - * @label - the label to update/replace
> + * @label: the label to update/replace
>   *
>   * Returns: new label that is up to date
>   *     else NULL on failure

Thanks,
Georgia

Re: [PATCH -next 10/11] apparmor: Fix kernel-doc warnings in apparmor/policy_compat.c

[Georgia Garcia]

Hi, Gaosheng Cui

On Sun, 2023-06-25 at 09:13 +0800, Gaosheng Cui wrote:
> Fix kernel-doc warnings:
> 
> security/apparmor/policy_compat.c:151: warning: Function parameter
> or member 'size' not described in 'compute_fperms'
> 
> Signed-off-by: Gaosheng Cui <cuigaosheng1@huawei.com>
> ---
>  security/apparmor/policy_compat.c | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/security/apparmor/policy_compat.c b/security/apparmor/policy_compat.c
> index 0cb02da8a319..18e4ddccf623 100644
> --- a/security/apparmor/policy_compat.c
> +++ b/security/apparmor/policy_compat.c
> @@ -143,6 +143,7 @@ static struct aa_perms compute_fperms_other(struct aa_dfa *dfa,
>   * compute_fperms - convert dfa compressed perms to internal perms and store
>   *		    them so they can be retrieved later.
>   * @dfa: a dfa using fperms to remap to internal permissions
> + * @size: the permission table size

I believe the size is returned, right?

>   *
>   * Returns: remapped perm table
>   */

Thanks,
Georgia

Re: [PATCH -next 00/11] Fix kernel-doc warnings in apparmor

[John Johansen]

On 6/24/23 18:13, Gaosheng Cui wrote:
> Fix kernel-doc warnings in apparmor, thanks very much!
> 
I have pulled these into the private testing repo, at
https://gitlab.com/jjohansen/apparmor-kernel

if there aren't revisions to 5/11 andd 10/11 this week
I will add a patch ontop to do the suggested revision.
If you post new versions I will pull those in and rebase,
before pushing these up to the more public repos.


> Gaosheng Cui (11):
>    apparmor: Fix kernel-doc warnings in apparmor/audit.c
>    apparmor: Fix kernel-doc warnings in apparmor/capability.c
>    apparmor: Fix kernel-doc warnings in apparmor/domain.c
>    apparmor: Fix kernel-doc warnings in apparmor/file.c
>    apparmor: Fix kernel-doc warnings in apparmor/label.c
>    apparmor: Fix kernel-doc warnings in apparmor/lib.c
>    apparmor: Fix kernel-doc warnings in apparmor/match.c
>    apparmor: Fix kernel-doc warnings in apparmor/resource.c
>    apparmor: Fix kernel-doc warnings in apparmor/policy_unpack.c
>    apparmor: Fix kernel-doc warnings in apparmor/policy_compat.c
>    apparmor: Fix kernel-doc warnings in apparmor/policy.c
> 
>   security/apparmor/audit.c         |  1 +
>   security/apparmor/capability.c    |  4 ++--
>   security/apparmor/domain.c        | 10 ++++++----
>   security/apparmor/file.c          |  6 +++---
>   security/apparmor/label.c         | 20 +++++++++++---------
>   security/apparmor/lib.c           |  4 ++--
>   security/apparmor/match.c         |  4 ++--
>   security/apparmor/policy.c        | 17 ++++++++++-------
>   security/apparmor/policy_compat.c |  1 +
>   security/apparmor/policy_unpack.c |  2 +-
>   security/apparmor/resource.c      |  8 ++++----
>   11 files changed, 43 insertions(+), 34 deletions(-)
> 

Re: [PATCH -next 00/11] Fix kernel-doc warnings in apparmor

[cuigaosheng]

Thanks for taking time to review these patches!

> I have pulled these into the private testing repo, at
> https://gitlab.com/jjohansen/apparmor-kernel
>
> if there aren't revisions to 5/11 andd 10/11 this week
> I will add a patch ontop to do the suggested revision.
> If you post new versions I will pull those in and rebase,
> before pushing these up to the more public repos.
>
These patches have been pulled into the private testing repo,
so please add a patch ontop to do the suggested revision，
thanks again for your work.


On 2023/7/10 16:45, John Johansen wrote:
> On 6/24/23 18:13, Gaosheng Cui wrote:
>> Fix kernel-doc warnings in apparmor, thanks very much!
>>
> I have pulled these into the private testing repo, at
> https://gitlab.com/jjohansen/apparmor-kernel
>
> if there aren't revisions to 5/11 andd 10/11 this week
> I will add a patch ontop to do the suggested revision.
> If you post new versions I will pull those in and rebase,
> before pushing these up to the more public repos.
>
>
>> Gaosheng Cui (11):
>>    apparmor: Fix kernel-doc warnings in apparmor/audit.c
>>    apparmor: Fix kernel-doc warnings in apparmor/capability.c
>>    apparmor: Fix kernel-doc warnings in apparmor/domain.c
>>    apparmor: Fix kernel-doc warnings in apparmor/file.c
>>    apparmor: Fix kernel-doc warnings in apparmor/label.c
>>    apparmor: Fix kernel-doc warnings in apparmor/lib.c
>>    apparmor: Fix kernel-doc warnings in apparmor/match.c
>>    apparmor: Fix kernel-doc warnings in apparmor/resource.c
>>    apparmor: Fix kernel-doc warnings in apparmor/policy_unpack.c
>>    apparmor: Fix kernel-doc warnings in apparmor/policy_compat.c
>>    apparmor: Fix kernel-doc warnings in apparmor/policy.c
>>
>>   security/apparmor/audit.c         |  1 +
>>   security/apparmor/capability.c    |  4 ++--
>>   security/apparmor/domain.c        | 10 ++++++----
>>   security/apparmor/file.c          |  6 +++---
>>   security/apparmor/label.c         | 20 +++++++++++---------
>>   security/apparmor/lib.c           |  4 ++--
>>   security/apparmor/match.c         |  4 ++--
>>   security/apparmor/policy.c        | 17 ++++++++++-------
>>   security/apparmor/policy_compat.c |  1 +
>>   security/apparmor/policy_unpack.c |  2 +-
>>   security/apparmor/resource.c      |  8 ++++----
>>   11 files changed, 43 insertions(+), 34 deletions(-)
>>
>
> .