On Wed, Oct 12, 2022 at 07:04:38PM +0200, Kevin Brodsky wrote:
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.
I did a quick scan through the code, and indeed it seems it is not applicable in this case.
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.
I was actually thinking of having the indentation aligned with the start of the description itself, so same as for arguments:
" If the ``@argument`` description has multiple lines, the continuation of the description should start at the same column as the previous line::"
but no strong opinion here.
--- BR B.
- @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