* [PATCH 1/2] fs: eventpoll: fix comments & kernel-doc notation
@ 2021-02-10 4:25 Randy Dunlap
2021-02-10 4:25 ` [PATCH 2/2] Docs: add fs/eventpoll to docbooks Randy Dunlap
2021-03-01 22:27 ` [PATCH 1/2] fs: eventpoll: fix comments & kernel-doc notation Jonathan Corbet
0 siblings, 2 replies; 3+ messages in thread
From: Randy Dunlap @ 2021-02-10 4:25 UTC (permalink / raw)
To: linux-kernel
Cc: Randy Dunlap, Jonathan Corbet, linux-doc, Andrew Morton, Alexander Viro
Use the documented kernel-doc format for function Return: descriptions.
Begin constant values in kernel-doc comments with '%'.
Remove kernel-doc "/**" from 2 functions that are not documented with
kernel-doc notation.
Fix typos, punctuation, & grammar.
Also fix a few kernel-doc warnings:
../fs/eventpoll.c:1883: warning: Function parameter or member 'ep' not described in 'ep_loop_check_proc'
../fs/eventpoll.c:1883: warning: Excess function parameter 'priv' description in 'ep_loop_check_proc'
../fs/eventpoll.c:1932: warning: Function parameter or member 'ep' not described in 'ep_loop_check'
../fs/eventpoll.c:1932: warning: Excess function parameter 'from' description in 'ep_loop_check'
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: Alexander Viro <viro@zeniv.linux.org.uk>
---
Jon: Al says that he is OK with one of you merging this fs/
(only comments) patch.
fs/eventpoll.c | 52 +++++++++++++++++++++++------------------------
1 file changed, 26 insertions(+), 26 deletions(-)
--- linux-next-20210205.orig/fs/eventpoll.c
+++ linux-next-20210205/fs/eventpoll.c
@@ -366,8 +366,8 @@ static inline struct epitem *ep_item_fro
*
* @ep: Pointer to the eventpoll context.
*
- * Returns: Returns a value different than zero if ready events are available,
- * or zero otherwise.
+ * Return: a value different than %zero if ready events are available,
+ * or %zero otherwise.
*/
static inline int ep_events_available(struct eventpoll *ep)
{
@@ -1023,7 +1023,7 @@ struct file *get_epoll_tfile_raw_ptr(str
}
#endif /* CONFIG_CHECKPOINT_RESTORE */
-/**
+/*
* Adds a new entry to the tail of the list in a lockless way, i.e.
* multiple CPUs are allowed to call this function concurrently.
*
@@ -1035,10 +1035,10 @@ struct file *get_epoll_tfile_raw_ptr(str
* completed.
*
* Also an element can be locklessly added to the list only in one
- * direction i.e. either to the tail either to the head, otherwise
+ * direction i.e. either to the tail or to the head, otherwise
* concurrent access will corrupt the list.
*
- * Returns %false if element has been already added to the list, %true
+ * Return: %false if element has been already added to the list, %true
* otherwise.
*/
static inline bool list_add_tail_lockless(struct list_head *new,
@@ -1076,11 +1076,11 @@ static inline bool list_add_tail_lockles
return true;
}
-/**
+/*
* Chains a new epi entry to the tail of the ep->ovflist in a lockless way,
* i.e. multiple CPUs are allowed to call this function concurrently.
*
- * Returns %false if epi element has been already chained, %true otherwise.
+ * Return: %false if epi element has been already chained, %true otherwise.
*/
static inline bool chain_epi_lockless(struct epitem *epi)
{
@@ -1105,8 +1105,8 @@ static inline bool chain_epi_lockless(st
* mechanism. It is called by the stored file descriptors when they
* have events to report.
*
- * This callback takes a read lock in order not to content with concurrent
- * events from another file descriptors, thus all modifications to ->rdllist
+ * This callback takes a read lock in order not to contend with concurrent
+ * events from another file descriptor, thus all modifications to ->rdllist
* or ->ovflist are lockless. Read lock is paired with the write lock from
* ep_scan_ready_list(), which stops all list modifications and guarantees
* that lists state is seen correctly.
@@ -1335,8 +1335,8 @@ static int reverse_path_check_proc(struc
* paths such that we will spend all our time waking up
* eventpoll objects.
*
- * Returns: Returns zero if the proposed links don't create too many paths,
- * -1 otherwise.
+ * Return: %zero if the proposed links don't create too many paths,
+ * %-1 otherwise.
*/
static int reverse_path_check(void)
{
@@ -1734,7 +1734,7 @@ static struct timespec64 *ep_timeout_to_
}
/**
- * ep_poll - Retrieves ready events, and delivers them to the caller supplied
+ * ep_poll - Retrieves ready events, and delivers them to the caller-supplied
* event buffer.
*
* @ep: Pointer to the eventpoll context.
@@ -1747,7 +1747,7 @@ static struct timespec64 *ep_timeout_to_
* until at least one event has been retrieved (or an error
* occurred).
*
- * Returns: Returns the number of ready events which have been fetched, or an
+ * Return: the number of ready events which have been fetched, or an
* error code, in case of error.
*/
static int ep_poll(struct eventpoll *ep, struct epoll_event __user *events,
@@ -1774,9 +1774,9 @@ static int ep_poll(struct eventpoll *ep,
/*
* This call is racy: We may or may not see events that are being added
- * to the ready list under the lock (e.g., in IRQ callbacks). For, cases
+ * to the ready list under the lock (e.g., in IRQ callbacks). For cases
* with a non-zero timeout, this thread will check the ready list under
- * lock and will added to the wait queue. For, cases with a zero
+ * lock and will add to the wait queue. For cases with a zero
* timeout, the user by definition should not care and will have to
* recheck again.
*/
@@ -1869,15 +1869,15 @@ static int ep_poll(struct eventpoll *ep,
/**
* ep_loop_check_proc - verify that adding an epoll file inside another
- * epoll structure, does not violate the constraints, in
+ * epoll structure does not violate the constraints, in
* terms of closed loops, or too deep chains (which can
* result in excessive stack usage).
*
- * @priv: Pointer to the epoll file to be currently checked.
+ * @ep: the &struct eventpoll to be currently checked.
* @depth: Current depth of the path being checked.
*
- * Returns: Returns zero if adding the epoll @file inside current epoll
- * structure @ep does not violate the constraints, or -1 otherwise.
+ * Return: %zero if adding the epoll @file inside current epoll
+ * structure @ep does not violate the constraints, or %-1 otherwise.
*/
static int ep_loop_check_proc(struct eventpoll *ep, int depth)
{
@@ -1919,14 +1919,14 @@ static int ep_loop_check_proc(struct eve
/**
* ep_loop_check - Performs a check to verify that adding an epoll file (@to)
- * into another epoll file (represented by @from) does not create
+ * into another epoll file (represented by @ep) does not create
* closed loops or too deep chains.
*
- * @from: Pointer to the epoll we are inserting into.
+ * @ep: Pointer to the epoll we are inserting into.
* @to: Pointer to the epoll to be inserted.
*
- * Returns: Returns zero if adding the epoll @to inside the epoll @from
- * does not violate the constraints, or -1 otherwise.
+ * Return: %zero if adding the epoll @to inside the epoll @from
+ * does not violate the constraints, or %-1 otherwise.
*/
static int ep_loop_check(struct eventpoll *ep, struct eventpoll *to)
{
@@ -2074,8 +2074,8 @@ int do_epoll_ctl(int epfd, int op, int f
ep = f.file->private_data;
/*
- * When we insert an epoll file descriptor, inside another epoll file
- * descriptor, there is the change of creating closed loops, which are
+ * When we insert an epoll file descriptor inside another epoll file
+ * descriptor, there is the chance of creating closed loops, which are
* better be handled here, than in more critical paths. While we are
* checking for loops we also determine the list of files reachable
* and hang them on the tfile_check_list, so we can check that we
@@ -2113,7 +2113,7 @@ int do_epoll_ctl(int epfd, int op, int f
}
/*
- * Try to lookup the file inside our RB tree, Since we grabbed "mtx"
+ * Try to lookup the file inside our RB tree. Since we grabbed "mtx"
* above, we can be sure to be able to use the item looked up by
* ep_find() till we release the mutex.
*/
^ permalink raw reply [flat|nested] 3+ messages in thread
* [PATCH 2/2] Docs: add fs/eventpoll to docbooks
2021-02-10 4:25 [PATCH 1/2] fs: eventpoll: fix comments & kernel-doc notation Randy Dunlap
@ 2021-02-10 4:25 ` Randy Dunlap
2021-03-01 22:27 ` [PATCH 1/2] fs: eventpoll: fix comments & kernel-doc notation Jonathan Corbet
1 sibling, 0 replies; 3+ messages in thread
From: Randy Dunlap @ 2021-02-10 4:25 UTC (permalink / raw)
To: linux-kernel
Cc: Randy Dunlap, Jonathan Corbet, linux-doc, Andrew Morton, Alexander Viro
Add fs/eventpoll.c to the filesystem api-summary book.
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: Alexander Viro <viro@zeniv.linux.org.uk>
---
Documentation/filesystems/api-summary.rst | 6 ++++++
1 file changed, 6 insertions(+)
--- linux-next-20210205.orig/Documentation/filesystems/api-summary.rst
+++ linux-next-20210205/Documentation/filesystems/api-summary.rst
@@ -122,6 +122,12 @@ Events based on file descriptors
.. kernel-doc:: fs/eventfd.c
:export:
+eventpoll (epoll) interfaces
+============================
+
+.. kernel-doc:: fs/eventpoll.c
+ :internal:
+
The Filesystem for Exporting Kernel Objects
===========================================
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [PATCH 1/2] fs: eventpoll: fix comments & kernel-doc notation
2021-02-10 4:25 [PATCH 1/2] fs: eventpoll: fix comments & kernel-doc notation Randy Dunlap
2021-02-10 4:25 ` [PATCH 2/2] Docs: add fs/eventpoll to docbooks Randy Dunlap
@ 2021-03-01 22:27 ` Jonathan Corbet
1 sibling, 0 replies; 3+ messages in thread
From: Jonathan Corbet @ 2021-03-01 22:27 UTC (permalink / raw)
To: Randy Dunlap, linux-kernel
Cc: Randy Dunlap, linux-doc, Andrew Morton, Alexander Viro
Randy Dunlap <rdunlap@infradead.org> writes:
> Use the documented kernel-doc format for function Return: descriptions.
> Begin constant values in kernel-doc comments with '%'.
>
> Remove kernel-doc "/**" from 2 functions that are not documented with
> kernel-doc notation.
>
> Fix typos, punctuation, & grammar.
>
> Also fix a few kernel-doc warnings:
>
> ../fs/eventpoll.c:1883: warning: Function parameter or member 'ep' not described in 'ep_loop_check_proc'
> ../fs/eventpoll.c:1883: warning: Excess function parameter 'priv' description in 'ep_loop_check_proc'
> ../fs/eventpoll.c:1932: warning: Function parameter or member 'ep' not described in 'ep_loop_check'
> ../fs/eventpoll.c:1932: warning: Excess function parameter 'from' description in 'ep_loop_check'
>
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: linux-doc@vger.kernel.org
> Cc: Andrew Morton <akpm@linux-foundation.org>
> Cc: Alexander Viro <viro@zeniv.linux.org.uk>
> ---
> Jon: Al says that he is OK with one of you merging this fs/
> (only comments) patch.
>
> fs/eventpoll.c | 52 +++++++++++++++++++++++------------------------
> 1 file changed, 26 insertions(+), 26 deletions(-)
Both patches applied, thanks.
jon
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2021-03-01 22:29 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-02-10 4:25 [PATCH 1/2] fs: eventpoll: fix comments & kernel-doc notation Randy Dunlap
2021-02-10 4:25 ` [PATCH 2/2] Docs: add fs/eventpoll to docbooks Randy Dunlap
2021-03-01 22:27 ` [PATCH 1/2] fs: eventpoll: fix comments & kernel-doc notation Jonathan Corbet
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).