On 11/10/2022 21:59, Beata Michalska wrote:
So, out of curiosity, I did run: scripts/kernel-doc -v -none include/linux/user_ptr.h
I didn't even know about that functionality so thanks!
which did give some warnings on missing description for return values: the 'Returns xyz .....' should be 'Return: xyz ....'.
I hadn't realised these were required in principle, I'll add them. In most cases I'll just convert the main block into a "Return:" block with indentation as there's nothing else to say really.
That should not be a show stopper for this patch though. Also some of the comments could fall into 'Context' blocks ?
I think not really, as this is "Context" in a very specific kernel sense, as per the documentation:
* * Context: Describes whether the function can sleep, what locks it takes, * releases, or expects to be held. It can extend over multiple * lines.
Not sure though what is exact scope of intended changes here so feel free to ignore the comments here.
Might as well make kernel-doc happy, this way we have a clear guideline for the future. It does complain about not understanding __capability in cheri.h but we can ignore that.
On Wed, Sep 28, 2022 at 04:31:41PM +0100, Kevin Brodsky wrote:
Format kernel-doc comments as per the recommendations in Documentation/doc-guide/kernel-doc.rst.
Signed-off-by: Kevin Brodsky kevin.brodsky@arm.com
include/linux/user_ptr.h | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-)
diff --git a/include/linux/user_ptr.h b/include/linux/user_ptr.h index e2de3464bcf8..152eb7af6dde 100644 --- a/include/linux/user_ptr.h +++ b/include/linux/user_ptr.h @@ -9,8 +9,8 @@ #endif /**
- as_user_ptr - convert an arbitrary integer value to a user pointer
- @x: the integer value to convert
- as_user_ptr() - Convert an arbitrary integer value to a user pointer.
- @x: The integer value to convert.
- Returns @x represented as a user pointer. The result is not a valid pointer
- and shall not be dereferenced.
@@ -30,8 +30,8 @@ #ifndef uaddr_to_user_ptr /**
- uaddr_to_user_ptr - convert a user-provided address to a user pointer
- @addr: the address to set the pointer to
- uaddr_to_user_ptr() - Convert a user-provided address to a user pointer.
- @addr: The address to set the pointer to.
- Returns a user pointer with its address set to @addr.
@@ -50,8 +50,9 @@ static inline void __user *uaddr_to_user_ptr(ptraddr_t addr) #ifndef uaddr_to_user_ptr_safe /**
- uaddr_to_user_ptr_safe - convert a kernel-generated user address to a user pointer
- @addr: the address to set the pointer to
- uaddr_to_user_ptr_safe() - Convert a kernel-generated user address to a
- user pointer.
This one seems bit weird. The guidelines do mention indentation for mutli-line argument description, not for function brief description though. So I guess we could either follow the arguments formatting or get rid of this indent whatsoever maybe ?
I wanted feedback on this one actually as it is indeed not specified, but I kind of felt that some indentation made it easier to read. If you feel it's better without I can easily remove it.
- @addr: The address to set the pointer to.
- Returns a user pointer with its address set to @addr.
@@ -66,8 +67,8 @@ static inline void __user *uaddr_to_user_ptr_safe(ptraddr_t addr) #endif /**
- user_ptr_addr - extract the address of a user pointer
- @ptr: the user pointer to extract the address from
- user_ptr_addr() - Extract the address of a user pointer.
*/
- @ptr: The user pointer to extract the address from.
- Returns the address @ptr points to.
@@ -77,7 +78,7 @@ static inline ptraddr_t user_ptr_addr(const void __user *ptr) } /**
- user_ptr_is_same - checks where two user pointers are exactly the same
- user_ptr_is_same() - Checks where two user pointers are exactly the same.
scripts/kernel-doc does complain about missing arguments' description.
Will add too (just to make it happy as it's really quite self-descriptive :) ).
Kevin
BR B.
- Returns true if @p1 and @p2 are exactly the same user pointers.
-- 2.34.1
linux-morello mailing list -- linux-morello@op-lists.linaro.org To unsubscribe send an email to linux-morello-leave@op-lists.linaro.org
linux-morello mailing list -- linux-morello@op-lists.linaro.org To unsubscribe send an email to linux-morello-leave@op-lists.linaro.org