Re: [PATCH] usb: fix some scripts/kernel-doc warnings
On 08/06/2013 12:28 AM, Greg Kroah-Hartman wrote: > On Mon, Aug 05, 2013 at 08:36:39PM +0200, Yacine Belkadi wrote: >> On 08/04/2013 11:29 PM, Greg Kroah-Hartman wrote: >>> On Sun, Aug 04, 2013 at 10:05:36PM +0200, Yacine Belkadi wrote: >>>> On 08/03/2013 05:29 AM, Greg Kroah-Hartman wrote: >>>>> On Fri, Aug 02, 2013 at 08:10:04PM +0200, Yacine Belkadi wrote: >>>>>> When building the htmldocs (in verbose mode), scripts/kernel-doc reports >>>>>> the >>>>>> following type of warnings: >>>>>> >>>>>> Warning(drivers/usb/core/usb.c:76): No description found for return >>>>>> value of >>>>>> 'usb_find_alt_setting' >>>>>> >>>>>> Fix them by: >>>>>> - adding some missing descriptions of return values >>>>>> - using "Return" sections for those descriptions >>>>>> >>>>>> Signed-off-by: Yacine Belkadi >>>>>> --- >>>>>> >>>>>> Applied to b3a3a9c441e2c8f6b6760de9331023a7906a4ac6 >>>>> >>>>> What does this line mean? >>>> >>>> It's the commit on which I created and applied the patch: >>>> >>>> commit b3a3a9c441e2c8f6b6760de9331023a7906a4ac6 >>>> Merge: a582e5f e70e78e >>>> Author: Linus Torvalds >>>> Date: Mon Jul 22 19:07:24 2013 -0700 >>> >>> Odd, I've never seen anyone use that before. It's really not needed, so >>> you don't have to do that in the future. >>> >> >> In hindsight, I should probably have used something like: >> "Patch against commit b3a3a9c441e2c8f6b6760de9331023a7906a4ac6". >> >> I thought this information may prove useful in some cases, because of the >> nature of the patch, which only modifies comments and may get out of sync >> with the code. >> >> Here is an example: >> - My local HEAD is at commit c1 when I start creating the patch. >> - Some function f doesn't have a description for its return value. I look >> into the code and deduce the description. So the description I add is based >> on the code at the commit c1. >> - Someone else submits a patch that changes the code of the function f, but >> I don't see it. >> - I send my patch to the maintainer. >> - My patch may apply cleanly on top of the other patch (mine only touched >> the comments), but the description now doesn't match the function's code, >> which is a problem. >> >> I assumed that if I specify the commit on which I worked, it may help the >> maintainer decide whether my patch got invalidated by some other patch that >> was applied first. Continuing with the example: The maintainer sees that I >> worked based on c1, but knows that a patch was applied in the mean time, so >> he/she asks me to update my patch first. >> >> What do you think? > > It does make sense, but please use terms that we can understand. If I > see a sha id, I have to go dig through a kernel tree to see what it > represents, which takes time (remember, I deal with thousands of > patches). If you said "Patch based on 3.11-rc1" then I know exactly > what that is, and how to handle it if there are merge errors. Noted. Thanks! Yacine -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH] usb: fix some scripts/kernel-doc warnings
On 08/06/2013 12:28 AM, Greg Kroah-Hartman wrote: On Mon, Aug 05, 2013 at 08:36:39PM +0200, Yacine Belkadi wrote: On 08/04/2013 11:29 PM, Greg Kroah-Hartman wrote: On Sun, Aug 04, 2013 at 10:05:36PM +0200, Yacine Belkadi wrote: On 08/03/2013 05:29 AM, Greg Kroah-Hartman wrote: On Fri, Aug 02, 2013 at 08:10:04PM +0200, Yacine Belkadi wrote: When building the htmldocs (in verbose mode), scripts/kernel-doc reports the following type of warnings: Warning(drivers/usb/core/usb.c:76): No description found for return value of 'usb_find_alt_setting' Fix them by: - adding some missing descriptions of return values - using Return sections for those descriptions Signed-off-by: Yacine Belkadi yacine.belkad...@gmail.com --- Applied to b3a3a9c441e2c8f6b6760de9331023a7906a4ac6 What does this line mean? It's the commit on which I created and applied the patch: commit b3a3a9c441e2c8f6b6760de9331023a7906a4ac6 Merge: a582e5f e70e78e Author: Linus Torvalds torva...@linux-foundation.org Date: Mon Jul 22 19:07:24 2013 -0700 Odd, I've never seen anyone use that before. It's really not needed, so you don't have to do that in the future. In hindsight, I should probably have used something like: Patch against commit b3a3a9c441e2c8f6b6760de9331023a7906a4ac6. I thought this information may prove useful in some cases, because of the nature of the patch, which only modifies comments and may get out of sync with the code. Here is an example: - My local HEAD is at commit c1 when I start creating the patch. - Some function f doesn't have a description for its return value. I look into the code and deduce the description. So the description I add is based on the code at the commit c1. - Someone else submits a patch that changes the code of the function f, but I don't see it. - I send my patch to the maintainer. - My patch may apply cleanly on top of the other patch (mine only touched the comments), but the description now doesn't match the function's code, which is a problem. I assumed that if I specify the commit on which I worked, it may help the maintainer decide whether my patch got invalidated by some other patch that was applied first. Continuing with the example: The maintainer sees that I worked based on c1, but knows that a patch was applied in the mean time, so he/she asks me to update my patch first. What do you think? It does make sense, but please use terms that we can understand. If I see a sha id, I have to go dig through a kernel tree to see what it represents, which takes time (remember, I deal with thousands of patches). If you said Patch based on 3.11-rc1 then I know exactly what that is, and how to handle it if there are merge errors. Noted. Thanks! Yacine -- To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH] usb: fix some scripts/kernel-doc warnings
On 08/04/2013 11:29 PM, Greg Kroah-Hartman wrote: > On Sun, Aug 04, 2013 at 10:05:36PM +0200, Yacine Belkadi wrote: >> On 08/03/2013 05:29 AM, Greg Kroah-Hartman wrote: >>> On Fri, Aug 02, 2013 at 08:10:04PM +0200, Yacine Belkadi wrote: >>>> When building the htmldocs (in verbose mode), scripts/kernel-doc reports >>>> the >>>> following type of warnings: >>>> >>>> Warning(drivers/usb/core/usb.c:76): No description found for return value >>>> of >>>> 'usb_find_alt_setting' >>>> >>>> Fix them by: >>>> - adding some missing descriptions of return values >>>> - using "Return" sections for those descriptions >>>> >>>> Signed-off-by: Yacine Belkadi >>>> --- >>>> >>>> Applied to b3a3a9c441e2c8f6b6760de9331023a7906a4ac6 >>> >>> What does this line mean? >> >> It's the commit on which I created and applied the patch: >> >> commit b3a3a9c441e2c8f6b6760de9331023a7906a4ac6 >> Merge: a582e5f e70e78e >> Author: Linus Torvalds >> Date: Mon Jul 22 19:07:24 2013 -0700 > > Odd, I've never seen anyone use that before. It's really not needed, so > you don't have to do that in the future. > In hindsight, I should probably have used something like: "Patch against commit b3a3a9c441e2c8f6b6760de9331023a7906a4ac6". I thought this information may prove useful in some cases, because of the nature of the patch, which only modifies comments and may get out of sync with the code. Here is an example: - My local HEAD is at commit c1 when I start creating the patch. - Some function f doesn't have a description for its return value. I look into the code and deduce the description. So the description I add is based on the code at the commit c1. - Someone else submits a patch that changes the code of the function f, but I don't see it. - I send my patch to the maintainer. - My patch may apply cleanly on top of the other patch (mine only touched the comments), but the description now doesn't match the function's code, which is a problem. I assumed that if I specify the commit on which I worked, it may help the maintainer decide whether my patch got invalidated by some other patch that was applied first. Continuing with the example: The maintainer sees that I worked based on c1, but knows that a patch was applied in the mean time, so he/she asks me to update my patch first. What do you think? Thanks, Yacine -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH] usb: fix some scripts/kernel-doc warnings
On 08/04/2013 11:29 PM, Greg Kroah-Hartman wrote: On Sun, Aug 04, 2013 at 10:05:36PM +0200, Yacine Belkadi wrote: On 08/03/2013 05:29 AM, Greg Kroah-Hartman wrote: On Fri, Aug 02, 2013 at 08:10:04PM +0200, Yacine Belkadi wrote: When building the htmldocs (in verbose mode), scripts/kernel-doc reports the following type of warnings: Warning(drivers/usb/core/usb.c:76): No description found for return value of 'usb_find_alt_setting' Fix them by: - adding some missing descriptions of return values - using Return sections for those descriptions Signed-off-by: Yacine Belkadi yacine.belkad...@gmail.com --- Applied to b3a3a9c441e2c8f6b6760de9331023a7906a4ac6 What does this line mean? It's the commit on which I created and applied the patch: commit b3a3a9c441e2c8f6b6760de9331023a7906a4ac6 Merge: a582e5f e70e78e Author: Linus Torvalds torva...@linux-foundation.org Date: Mon Jul 22 19:07:24 2013 -0700 Odd, I've never seen anyone use that before. It's really not needed, so you don't have to do that in the future. In hindsight, I should probably have used something like: Patch against commit b3a3a9c441e2c8f6b6760de9331023a7906a4ac6. I thought this information may prove useful in some cases, because of the nature of the patch, which only modifies comments and may get out of sync with the code. Here is an example: - My local HEAD is at commit c1 when I start creating the patch. - Some function f doesn't have a description for its return value. I look into the code and deduce the description. So the description I add is based on the code at the commit c1. - Someone else submits a patch that changes the code of the function f, but I don't see it. - I send my patch to the maintainer. - My patch may apply cleanly on top of the other patch (mine only touched the comments), but the description now doesn't match the function's code, which is a problem. I assumed that if I specify the commit on which I worked, it may help the maintainer decide whether my patch got invalidated by some other patch that was applied first. Continuing with the example: The maintainer sees that I worked based on c1, but knows that a patch was applied in the mean time, so he/she asks me to update my patch first. What do you think? Thanks, Yacine -- To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH] usb: fix some scripts/kernel-doc warnings
On 08/03/2013 05:29 AM, Greg Kroah-Hartman wrote: > On Fri, Aug 02, 2013 at 08:10:04PM +0200, Yacine Belkadi wrote: >> When building the htmldocs (in verbose mode), scripts/kernel-doc reports the >> following type of warnings: >> >> Warning(drivers/usb/core/usb.c:76): No description found for return value of >> 'usb_find_alt_setting' >> >> Fix them by: >> - adding some missing descriptions of return values >> - using "Return" sections for those descriptions >> >> Signed-off-by: Yacine Belkadi >> --- >> >> Applied to b3a3a9c441e2c8f6b6760de9331023a7906a4ac6 > > What does this line mean? It's the commit on which I created and applied the patch: commit b3a3a9c441e2c8f6b6760de9331023a7906a4ac6 Merge: a582e5f e70e78e Author: Linus Torvalds Date: Mon Jul 22 19:07:24 2013 -0700 Merge tag 'trace-3.11-rc2' of git://git.kernel.org/pub/scm/linux/kernel/git/rostedt/linux-trace Yacine -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH] usb: fix some scripts/kernel-doc warnings
On 08/03/2013 05:29 AM, Greg Kroah-Hartman wrote: On Fri, Aug 02, 2013 at 08:10:04PM +0200, Yacine Belkadi wrote: When building the htmldocs (in verbose mode), scripts/kernel-doc reports the following type of warnings: Warning(drivers/usb/core/usb.c:76): No description found for return value of 'usb_find_alt_setting' Fix them by: - adding some missing descriptions of return values - using Return sections for those descriptions Signed-off-by: Yacine Belkadi yacine.belkad...@gmail.com --- Applied to b3a3a9c441e2c8f6b6760de9331023a7906a4ac6 What does this line mean? It's the commit on which I created and applied the patch: commit b3a3a9c441e2c8f6b6760de9331023a7906a4ac6 Merge: a582e5f e70e78e Author: Linus Torvalds torva...@linux-foundation.org Date: Mon Jul 22 19:07:24 2013 -0700 Merge tag 'trace-3.11-rc2' of git://git.kernel.org/pub/scm/linux/kernel/git/rostedt/linux-trace Yacine -- To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
[PATCH] usb: fix some scripts/kernel-doc warnings
When building the htmldocs (in verbose mode), scripts/kernel-doc reports the
following type of warnings:
Warning(drivers/usb/core/usb.c:76): No description found for return value of
'usb_find_alt_setting'
Fix them by:
- adding some missing descriptions of return values
- using "Return" sections for those descriptions
Signed-off-by: Yacine Belkadi
---
Applied to b3a3a9c441e2c8f6b6760de9331023a7906a4ac6
drivers/usb/core/buffer.c |5 ++--
drivers/usb/core/driver.c | 22 ++--
drivers/usb/core/file.c|2 +-
drivers/usb/core/hcd-pci.c |2 ++
drivers/usb/core/hcd.c | 37 +++
drivers/usb/core/hub.c | 37 +++
drivers/usb/core/message.c | 49
drivers/usb/core/urb.c | 34 -
drivers/usb/core/usb.c | 60 +++-
include/linux/usb.h| 12 ++---
10 files changed, 173 insertions(+), 87 deletions(-)
diff --git a/drivers/usb/core/buffer.c b/drivers/usb/core/buffer.c
index b0585e6..2355974 100644
--- a/drivers/usb/core/buffer.c
+++ b/drivers/usb/core/buffer.c
@@ -43,10 +43,11 @@ static const size_t pool_max[HCD_BUFFER_POOLS] = {
*
* Call this as part of initializing a host controller that uses the dma
* memory allocators. It initializes some pools of dma-coherent memory that
- * will be shared by all drivers using that controller, or returns a negative
- * errno value on error.
+ * will be shared by all drivers using that controller.
*
* Call hcd_buffer_destroy() to clean up after using those pools.
+ *
+ * Return: 0 if successful. A negative errno value otherwise.
*/
int hcd_buffer_create(struct usb_hcd *hcd)
{
diff --git a/drivers/usb/core/driver.c b/drivers/usb/core/driver.c
index 7609ac4..124bcc5 100644
--- a/drivers/usb/core/driver.c
+++ b/drivers/usb/core/driver.c
@@ -117,6 +117,8 @@ static DRIVER_ATTR(new_id, S_IRUGO | S_IWUSR, show_dynids,
store_new_id);
* @count: input size
*
* Removes a dynamic usb device ID from this driver.
+ *
+ * Return: @count on success. A negative error code otherwise.
*/
static ssize_t
store_remove_id(struct device_driver *driver, const char *buf, size_t count)
@@ -457,6 +459,8 @@ static int usb_unbind_interface(struct device *dev)
* Callers must own the device lock, so driver probe() entries don't need
* extra locking, but other call contexts may need to explicitly claim that
* lock.
+ *
+ * Return: 0 on success.
*/
int usb_driver_claim_interface(struct usb_driver *driver,
struct usb_interface *iface, void *priv)
@@ -658,6 +662,8 @@ EXPORT_SYMBOL_GPL(usb_match_one_id);
* These device tables are exported with MODULE_DEVICE_TABLE, through
* modutils, to support the driver loading functionality of USB hotplugging.
*
+ * Return: The first matching usb_device_id, or %NULL.
+ *
* What Matches:
*
* The "match_flags" element in a usb_device_id controls which
@@ -823,7 +829,8 @@ static int usb_uevent(struct device *dev, struct
kobj_uevent_env *env)
* Registers a USB device driver with the USB core. The list of
* unattached devices will be rescanned whenever a new driver is
* added, allowing the new driver to attach to any recognized devices.
- * Returns a negative error code on failure and 0 on success.
+ *
+ * Return: A negative error code on failure and 0 on success.
*/
int usb_register_device_driver(struct usb_device_driver *new_udriver,
struct module *owner)
@@ -879,7 +886,8 @@ EXPORT_SYMBOL_GPL(usb_deregister_device_driver);
* Registers a USB interface driver with the USB core. The list of
* unattached interfaces will be rescanned whenever a new driver is
* added, allowing the new driver to attach to any recognized interfaces.
- * Returns a negative error code on failure and 0 on success.
+ *
+ * Return: A negative error code on failure and 0 on success.
*
* NOTE: if you want your driver to use the USB major number, you must call
* usb_register_dev() to enable that functionality. This function no longer
@@ -1213,6 +1221,8 @@ done:
* unpredictable times.
*
* This routine can run only in process context.
+ *
+ * Return: 0 if the suspend succeeded.
*/
static int usb_suspend_both(struct usb_device *udev, pm_message_t msg)
{
@@ -1294,6 +1304,8 @@ static int usb_suspend_both(struct usb_device *udev,
pm_message_t msg)
* unpredictable times.
*
* This routine can run only in process context.
+ *
+ * Return: 0 on success.
*/
static int usb_resume_both(struct usb_device *udev, pm_message_t msg)
{
@@ -1491,6 +1503,8 @@ void usb_autosuspend_device(struct usb_device *udev)
* The caller must hold @udev's device lock.
*
* This routine can run only in process context.
+ *
+ * Return: 0 on success. A negative error code otherwise.
*/
int usb_autoresume_device(struct usb_device *udev)
{
@@ -1600,6 +1614,8
[PATCH] usb: fix some scripts/kernel-doc warnings
When building the htmldocs (in verbose mode), scripts/kernel-doc reports the
following type of warnings:
Warning(drivers/usb/core/usb.c:76): No description found for return value of
'usb_find_alt_setting'
Fix them by:
- adding some missing descriptions of return values
- using Return sections for those descriptions
Signed-off-by: Yacine Belkadi yacine.belkad...@gmail.com
---
Applied to b3a3a9c441e2c8f6b6760de9331023a7906a4ac6
drivers/usb/core/buffer.c |5 ++--
drivers/usb/core/driver.c | 22 ++--
drivers/usb/core/file.c|2 +-
drivers/usb/core/hcd-pci.c |2 ++
drivers/usb/core/hcd.c | 37 +++
drivers/usb/core/hub.c | 37 +++
drivers/usb/core/message.c | 49
drivers/usb/core/urb.c | 34 -
drivers/usb/core/usb.c | 60 +++-
include/linux/usb.h| 12 ++---
10 files changed, 173 insertions(+), 87 deletions(-)
diff --git a/drivers/usb/core/buffer.c b/drivers/usb/core/buffer.c
index b0585e6..2355974 100644
--- a/drivers/usb/core/buffer.c
+++ b/drivers/usb/core/buffer.c
@@ -43,10 +43,11 @@ static const size_t pool_max[HCD_BUFFER_POOLS] = {
*
* Call this as part of initializing a host controller that uses the dma
* memory allocators. It initializes some pools of dma-coherent memory that
- * will be shared by all drivers using that controller, or returns a negative
- * errno value on error.
+ * will be shared by all drivers using that controller.
*
* Call hcd_buffer_destroy() to clean up after using those pools.
+ *
+ * Return: 0 if successful. A negative errno value otherwise.
*/
int hcd_buffer_create(struct usb_hcd *hcd)
{
diff --git a/drivers/usb/core/driver.c b/drivers/usb/core/driver.c
index 7609ac4..124bcc5 100644
--- a/drivers/usb/core/driver.c
+++ b/drivers/usb/core/driver.c
@@ -117,6 +117,8 @@ static DRIVER_ATTR(new_id, S_IRUGO | S_IWUSR, show_dynids,
store_new_id);
* @count: input size
*
* Removes a dynamic usb device ID from this driver.
+ *
+ * Return: @count on success. A negative error code otherwise.
*/
static ssize_t
store_remove_id(struct device_driver *driver, const char *buf, size_t count)
@@ -457,6 +459,8 @@ static int usb_unbind_interface(struct device *dev)
* Callers must own the device lock, so driver probe() entries don't need
* extra locking, but other call contexts may need to explicitly claim that
* lock.
+ *
+ * Return: 0 on success.
*/
int usb_driver_claim_interface(struct usb_driver *driver,
struct usb_interface *iface, void *priv)
@@ -658,6 +662,8 @@ EXPORT_SYMBOL_GPL(usb_match_one_id);
* These device tables are exported with MODULE_DEVICE_TABLE, through
* modutils, to support the driver loading functionality of USB hotplugging.
*
+ * Return: The first matching usb_device_id, or %NULL.
+ *
* What Matches:
*
* The match_flags element in a usb_device_id controls which
@@ -823,7 +829,8 @@ static int usb_uevent(struct device *dev, struct
kobj_uevent_env *env)
* Registers a USB device driver with the USB core. The list of
* unattached devices will be rescanned whenever a new driver is
* added, allowing the new driver to attach to any recognized devices.
- * Returns a negative error code on failure and 0 on success.
+ *
+ * Return: A negative error code on failure and 0 on success.
*/
int usb_register_device_driver(struct usb_device_driver *new_udriver,
struct module *owner)
@@ -879,7 +886,8 @@ EXPORT_SYMBOL_GPL(usb_deregister_device_driver);
* Registers a USB interface driver with the USB core. The list of
* unattached interfaces will be rescanned whenever a new driver is
* added, allowing the new driver to attach to any recognized interfaces.
- * Returns a negative error code on failure and 0 on success.
+ *
+ * Return: A negative error code on failure and 0 on success.
*
* NOTE: if you want your driver to use the USB major number, you must call
* usb_register_dev() to enable that functionality. This function no longer
@@ -1213,6 +1221,8 @@ done:
* unpredictable times.
*
* This routine can run only in process context.
+ *
+ * Return: 0 if the suspend succeeded.
*/
static int usb_suspend_both(struct usb_device *udev, pm_message_t msg)
{
@@ -1294,6 +1304,8 @@ static int usb_suspend_both(struct usb_device *udev,
pm_message_t msg)
* unpredictable times.
*
* This routine can run only in process context.
+ *
+ * Return: 0 on success.
*/
static int usb_resume_both(struct usb_device *udev, pm_message_t msg)
{
@@ -1491,6 +1503,8 @@ void usb_autosuspend_device(struct usb_device *udev)
* The caller must hold @udev's device lock.
*
* This routine can run only in process context.
+ *
+ * Return: 0 on success. A negative error code otherwise.
*/
int usb_autoresume_device(struct usb_device *udev)
{
@@ -1600,6 +1614,8
[PATCH] workqueue: fix some scripts/kernel-doc warnings
When building the htmldocs (in verbose mode), scripts/kernel-doc reports the
following type of warnings:
Warning(kernel/workqueue.c:653): No description found for return value of
'get_work_pool'
Fix them by:
- Using "Return:" sections to introduce descriptions of return values
- Adding some missing descriptions
Signed-off-by: Yacine Belkadi
---
Applied to 61f98b0fca802d7e0191072606519e2230a6226d
kernel/workqueue.c | 107
1 file changed, 66 insertions(+), 41 deletions(-)
diff --git a/kernel/workqueue.c b/kernel/workqueue.c
index f02c4a4..08e2e97 100644
--- a/kernel/workqueue.c
+++ b/kernel/workqueue.c
@@ -540,6 +540,8 @@ static int worker_pool_assign_id(struct worker_pool *pool)
* This must be called either with pwq_lock held or sched RCU read locked.
* If the pwq needs to be used beyond the locking in effect, the caller is
* responsible for guaranteeing that the pwq stays online.
+ *
+ * Return: The unbound pool_workqueue for @node.
*/
static struct pool_workqueue *unbound_pwq_by_node(struct workqueue_struct *wq,
int node)
@@ -638,8 +640,6 @@ static struct pool_workqueue *get_work_pwq(struct
work_struct *work)
* get_work_pool - return the worker_pool a given work was associated with
* @work: the work item of interest
*
- * Return the worker_pool @work was last associated with. %NULL if none.
- *
* Pools are created and destroyed under wq_pool_mutex, and allows read
* access under sched-RCU read lock. As such, this function should be
* called under wq_pool_mutex or with preemption disabled.
@@ -648,6 +648,8 @@ static struct pool_workqueue *get_work_pwq(struct
work_struct *work)
* mentioned locking is in effect. If the returned pool needs to be used
* beyond the critical section, the caller is responsible for ensuring the
* returned pool is and stays online.
+ *
+ * Return: The worker_pool @work was last associated with. %NULL if none.
*/
static struct worker_pool *get_work_pool(struct work_struct *work)
{
@@ -671,7 +673,7 @@ static struct worker_pool *get_work_pool(struct work_struct
*work)
* get_work_pool_id - return the worker pool ID a given work is associated with
* @work: the work item of interest
*
- * Return the worker_pool ID @work was last associated with.
+ * Return: The worker_pool ID @work was last associated with.
* %WORK_OFFQ_POOL_NONE if none.
*/
static int get_work_pool_id(struct work_struct *work)
@@ -830,7 +832,7 @@ void wq_worker_waking_up(struct task_struct *task, int cpu)
* CONTEXT:
* spin_lock_irq(rq->lock)
*
- * RETURNS:
+ * Return:
* Worker task on @cpu to wake up, %NULL if none.
*/
struct task_struct *wq_worker_sleeping(struct task_struct *task, int cpu)
@@ -965,8 +967,8 @@ static inline void worker_clr_flags(struct worker *worker,
unsigned int flags)
* CONTEXT:
* spin_lock_irq(pool->lock).
*
- * RETURNS:
- * Pointer to worker which is executing @work if found, NULL
+ * Return:
+ * Pointer to worker which is executing @work if found, %NULL
* otherwise.
*/
static struct worker *find_worker_executing_work(struct worker_pool *pool,
@@ -1154,14 +1156,16 @@ out_put:
* @flags: place to store irq state
*
* Try to grab PENDING bit of @work. This function can handle @work in any
- * stable state - idle, on timer or on worklist. Return values are
+ * stable state - idle, on timer or on worklist.
*
+ * Return:
* 1 if @work was pending and we successfully stole PENDING
* 0 if @work was idle and we claimed PENDING
* -EAGAINif PENDING couldn't be grabbed at the moment, safe to busy-retry
* -ENOENTif someone else is canceling @work, this state may persist
* for arbitrarily long
*
+ * Note:
* On >= 0 return, the caller owns @work's PENDING bit. To avoid getting
* interrupted while holding PENDING and @work off queue, irq must be
* disabled on entry. This, combined with delayed_work->timer being
@@ -1403,10 +1407,10 @@ retry:
* @wq: workqueue to use
* @work: work to queue
*
- * Returns %false if @work was already on a queue, %true otherwise.
- *
* We queue the work to a specific CPU, the caller must ensure it
* can't go away.
+ *
+ * Return: %false if @work was already on a queue, %true otherwise.
*/
bool queue_work_on(int cpu, struct workqueue_struct *wq,
struct work_struct *work)
@@ -1476,7 +1480,7 @@ static void __queue_delayed_work(int cpu, struct
workqueue_struct *wq,
* @dwork: work to queue
* @delay: number of jiffies to wait before queueing
*
- * Returns %false if @work was already on a queue, %true otherwise. If
+ * Return: %false if @work was already on a queue, %true otherwise. If
* @delay is zero and @dwork is idle, it will be scheduled for immediate
* execution.
*/
@@ -1512,7 +1516,7 @@ EXPORT_SYMBOL(queue_delayed_work_on);
* zero, @work is guaranteed to be
[PATCH] workqueue: fix some scripts/kernel-doc warnings
When building the htmldocs (in verbose mode), scripts/kernel-doc reports the
following type of warnings:
Warning(kernel/workqueue.c:653): No description found for return value of
'get_work_pool'
Fix them by:
- Using Return: sections to introduce descriptions of return values
- Adding some missing descriptions
Signed-off-by: Yacine Belkadi yacine.belkad...@gmail.com
---
Applied to 61f98b0fca802d7e0191072606519e2230a6226d
kernel/workqueue.c | 107
1 file changed, 66 insertions(+), 41 deletions(-)
diff --git a/kernel/workqueue.c b/kernel/workqueue.c
index f02c4a4..08e2e97 100644
--- a/kernel/workqueue.c
+++ b/kernel/workqueue.c
@@ -540,6 +540,8 @@ static int worker_pool_assign_id(struct worker_pool *pool)
* This must be called either with pwq_lock held or sched RCU read locked.
* If the pwq needs to be used beyond the locking in effect, the caller is
* responsible for guaranteeing that the pwq stays online.
+ *
+ * Return: The unbound pool_workqueue for @node.
*/
static struct pool_workqueue *unbound_pwq_by_node(struct workqueue_struct *wq,
int node)
@@ -638,8 +640,6 @@ static struct pool_workqueue *get_work_pwq(struct
work_struct *work)
* get_work_pool - return the worker_pool a given work was associated with
* @work: the work item of interest
*
- * Return the worker_pool @work was last associated with. %NULL if none.
- *
* Pools are created and destroyed under wq_pool_mutex, and allows read
* access under sched-RCU read lock. As such, this function should be
* called under wq_pool_mutex or with preemption disabled.
@@ -648,6 +648,8 @@ static struct pool_workqueue *get_work_pwq(struct
work_struct *work)
* mentioned locking is in effect. If the returned pool needs to be used
* beyond the critical section, the caller is responsible for ensuring the
* returned pool is and stays online.
+ *
+ * Return: The worker_pool @work was last associated with. %NULL if none.
*/
static struct worker_pool *get_work_pool(struct work_struct *work)
{
@@ -671,7 +673,7 @@ static struct worker_pool *get_work_pool(struct work_struct
*work)
* get_work_pool_id - return the worker pool ID a given work is associated with
* @work: the work item of interest
*
- * Return the worker_pool ID @work was last associated with.
+ * Return: The worker_pool ID @work was last associated with.
* %WORK_OFFQ_POOL_NONE if none.
*/
static int get_work_pool_id(struct work_struct *work)
@@ -830,7 +832,7 @@ void wq_worker_waking_up(struct task_struct *task, int cpu)
* CONTEXT:
* spin_lock_irq(rq-lock)
*
- * RETURNS:
+ * Return:
* Worker task on @cpu to wake up, %NULL if none.
*/
struct task_struct *wq_worker_sleeping(struct task_struct *task, int cpu)
@@ -965,8 +967,8 @@ static inline void worker_clr_flags(struct worker *worker,
unsigned int flags)
* CONTEXT:
* spin_lock_irq(pool-lock).
*
- * RETURNS:
- * Pointer to worker which is executing @work if found, NULL
+ * Return:
+ * Pointer to worker which is executing @work if found, %NULL
* otherwise.
*/
static struct worker *find_worker_executing_work(struct worker_pool *pool,
@@ -1154,14 +1156,16 @@ out_put:
* @flags: place to store irq state
*
* Try to grab PENDING bit of @work. This function can handle @work in any
- * stable state - idle, on timer or on worklist. Return values are
+ * stable state - idle, on timer or on worklist.
*
+ * Return:
* 1 if @work was pending and we successfully stole PENDING
* 0 if @work was idle and we claimed PENDING
* -EAGAINif PENDING couldn't be grabbed at the moment, safe to busy-retry
* -ENOENTif someone else is canceling @work, this state may persist
* for arbitrarily long
*
+ * Note:
* On = 0 return, the caller owns @work's PENDING bit. To avoid getting
* interrupted while holding PENDING and @work off queue, irq must be
* disabled on entry. This, combined with delayed_work-timer being
@@ -1403,10 +1407,10 @@ retry:
* @wq: workqueue to use
* @work: work to queue
*
- * Returns %false if @work was already on a queue, %true otherwise.
- *
* We queue the work to a specific CPU, the caller must ensure it
* can't go away.
+ *
+ * Return: %false if @work was already on a queue, %true otherwise.
*/
bool queue_work_on(int cpu, struct workqueue_struct *wq,
struct work_struct *work)
@@ -1476,7 +1480,7 @@ static void __queue_delayed_work(int cpu, struct
workqueue_struct *wq,
* @dwork: work to queue
* @delay: number of jiffies to wait before queueing
*
- * Returns %false if @work was already on a queue, %true otherwise. If
+ * Return: %false if @work was already on a queue, %true otherwise. If
* @delay is zero and @dwork is idle, it will be scheduled for immediate
* execution.
*/
@@ -1512,7 +1516,7 @@ EXPORT_SYMBOL(queue_delayed_work_on);
* zero, @work is guaranteed to be scheduled
[PATCH] hrtimer, timer: fix some scripts/kernel-doc warnings
When building the htmldocs (in verbose mode), scripts/kernel-doc reports the
following type of warnings:
Warning(kernel/timer.c:230): No description found for return value of
'round_jiffies'
Fix them by:
- Using "Return:" sections to introduce the descriptions of return values.
- Adding missing descriptions.
Signed-off-by: Yacine Belkadi
---
Applied to d2b4a646717153a1a180b64d4a8464054dbd700e
kernel/hrtimer.c | 27 +--
kernel/timer.c | 40 ++--
2 files changed, 47 insertions(+), 20 deletions(-)
diff --git a/kernel/hrtimer.c b/kernel/hrtimer.c
index f0f4fe2..89696c9 100644
--- a/kernel/hrtimer.c
+++ b/kernel/hrtimer.c
@@ -277,7 +277,7 @@ lock_hrtimer_base(const struct hrtimer *timer, unsigned
long *flags)
* @kt:addend
* @nsec: the scalar nsec value to add
*
- * Returns the sum of kt and nsec in ktime_t format
+ * Return: The sum of @kt and @nsec in ktime_t format.
*/
ktime_t ktime_add_ns(const ktime_t kt, u64 nsec)
{
@@ -305,7 +305,7 @@ EXPORT_SYMBOL_GPL(ktime_add_ns);
* @kt:minuend
* @nsec: the scalar nsec value to subtract
*
- * Returns the subtraction of @nsec from @kt in ktime_t format
+ * Return: The subtraction of @nsec from @kt in ktime_t format.
*/
ktime_t ktime_sub_ns(const ktime_t kt, u64 nsec)
{
@@ -836,7 +836,8 @@ void unlock_hrtimer_base(const struct hrtimer *timer,
unsigned long *flags)
* @interval: the interval to forward
*
* Forward the timer expiry so it will expire in the future.
- * Returns the number of overruns.
+ *
+ * Return: The number of overruns.
*/
u64 hrtimer_forward(struct hrtimer *timer, ktime_t now, ktime_t interval)
{
@@ -1038,7 +1039,7 @@ int __hrtimer_start_range_ns(struct hrtimer *timer,
ktime_t tim,
* @mode: expiry mode: absolute (HRTIMER_MODE_ABS) or
* relative (HRTIMER_MODE_REL)
*
- * Returns:
+ * Return:
* 0 on success
* 1 when the timer was active
*/
@@ -1056,7 +1057,7 @@ EXPORT_SYMBOL_GPL(hrtimer_start_range_ns);
* @mode: expiry mode: absolute (HRTIMER_MODE_ABS) or
* relative (HRTIMER_MODE_REL)
*
- * Returns:
+ * Return:
* 0 on success
* 1 when the timer was active
*/
@@ -1072,7 +1073,7 @@ EXPORT_SYMBOL_GPL(hrtimer_start);
* hrtimer_try_to_cancel - try to deactivate a timer
* @timer: hrtimer to stop
*
- * Returns:
+ * Return:
* 0 when the timer was not active
* 1 when the timer was active
* -1 when the timer is currently excuting the callback function and
@@ -1100,7 +1101,7 @@ EXPORT_SYMBOL_GPL(hrtimer_try_to_cancel);
* hrtimer_cancel - cancel a timer and wait for the handler to finish.
* @timer: the timer to be cancelled
*
- * Returns:
+ * Return:
* 0 when the timer was not active
* 1 when the timer was active
*/
@@ -1119,6 +1120,8 @@ EXPORT_SYMBOL_GPL(hrtimer_cancel);
/**
* hrtimer_get_remaining - get remaining time for the timer
* @timer: the timer to read
+ *
+ * Return: The remaining time for @timer.
*/
ktime_t hrtimer_get_remaining(const struct hrtimer *timer)
{
@@ -1137,7 +1140,7 @@ EXPORT_SYMBOL_GPL(hrtimer_get_remaining);
/**
* hrtimer_get_next_event - get the time until next expiry event
*
- * Returns the delta to the next expiry event or KTIME_MAX if no timer
+ * Return: The delta to the next expiry event or KTIME_MAX if no timer
* is pending.
*/
ktime_t hrtimer_get_next_event(void)
@@ -1220,6 +1223,8 @@ EXPORT_SYMBOL_GPL(hrtimer_init);
*
* Store the resolution of the clock selected by @which_clock in the
* variable pointed to by @tp.
+ *
+ * Return: 0
*/
int hrtimer_get_res(const clockid_t which_clock, struct timespec *tp)
{
@@ -1793,6 +1798,8 @@ void __init hrtimers_init(void)
* @delta: slack in expires timeout (ktime_t)
* @mode: timer mode, HRTIMER_MODE_ABS or HRTIMER_MODE_REL
* @clock: timer clock, CLOCK_MONOTONIC or CLOCK_REALTIME
+ *
+ * Return: 0 when the timer has expired. Otherwise -EINTR.
*/
int __sched
schedule_hrtimeout_range_clock(ktime_t *expires, unsigned long delta,
@@ -1864,7 +1871,7 @@ schedule_hrtimeout_range_clock(ktime_t *expires, unsigned
long delta,
* The current task state is guaranteed to be TASK_RUNNING when this
* routine returns.
*
- * Returns 0 when the timer has expired otherwise -EINTR
+ * Return: 0 when the timer has expired. Otherwise -EINTR.
*/
int __sched schedule_hrtimeout_range(ktime_t *expires, unsigned long delta,
const enum hrtimer_mode mode)
@@ -1894,7 +1901,7 @@ EXPORT_SYMBOL_GPL(schedule_hrtimeout_range);
* The current task state is guaranteed to be TASK_RUNNING when this
* routine returns.
*
- * Returns 0 when the timer has expired otherwise -EINTR
+ * Return: 0 when the timer has expired. Otherwise -EINTR.
*/
int __sched schedule_hrtimeout(ktime_t *expires,
const enum hrtimer_mode mode)
diff --git a/kernel/timer.
[tip:sched/urgent] sched: Fix some kernel-doc warnings
Commit-ID: e69f61862ab833e9b8d3c15b6ce07fd69f3bfecc
Gitweb: http://git.kernel.org/tip/e69f61862ab833e9b8d3c15b6ce07fd69f3bfecc
Author: Yacine Belkadi
AuthorDate: Fri, 12 Jul 2013 20:45:47 +0200
Committer: Ingo Molnar
CommitDate: Thu, 18 Jul 2013 09:58:21 +0200
sched: Fix some kernel-doc warnings
When building the htmldocs (in verbose mode), scripts/kernel-doc
reports the follwing type of warnings:
Warning(kernel/sched/core.c:936): No description found for return value of
'task_curr'
...
Fix those by:
- adding the missing descriptions
- using "Return" sections for the descriptions
Signed-off-by: Yacine Belkadi
Cc: Peter Zijlstra
Link:
http://lkml.kernel.org/r/1373654747-2389-1-git-send-email-yacine.belkad...@gmail.com
[ While at it, fix the cpupri_set() explanation. ]
Signed-off-by: Ingo Molnar
---
include/linux/sched.h | 6
kernel/sched/core.c | 82 ++-
kernel/sched/cpupri.c | 4 +--
kernel/sched/fair.c | 9 --
4 files changed, 76 insertions(+), 25 deletions(-)
diff --git a/include/linux/sched.h b/include/linux/sched.h
index 50d04b9..8230024 100644
--- a/include/linux/sched.h
+++ b/include/linux/sched.h
@@ -1532,6 +1532,8 @@ static inline pid_t task_pgrp_nr(struct task_struct *tsk)
* Test if a process is not yet dead (at most zombie state)
* If pid_alive fails, then pointers within the task structure
* can be stale and must not be dereferenced.
+ *
+ * Return: 1 if the process is alive. 0 otherwise.
*/
static inline int pid_alive(struct task_struct *p)
{
@@ -1543,6 +1545,8 @@ static inline int pid_alive(struct task_struct *p)
* @tsk: Task structure to be checked.
*
* Check if a task structure is the first user space task the kernel created.
+ *
+ * Return: 1 if the task structure is init. 0 otherwise.
*/
static inline int is_global_init(struct task_struct *tsk)
{
@@ -1893,6 +1897,8 @@ extern struct task_struct *idle_task(int cpu);
/**
* is_idle_task - is the specified task an idle task?
* @p: the task in question.
+ *
+ * Return: 1 if @p is an idle task. 0 otherwise.
*/
static inline bool is_idle_task(const struct task_struct *p)
{
diff --git a/kernel/sched/core.c b/kernel/sched/core.c
index 0d8eb45..4c3967f 100644
--- a/kernel/sched/core.c
+++ b/kernel/sched/core.c
@@ -933,6 +933,8 @@ static int effective_prio(struct task_struct *p)
/**
* task_curr - is this task currently executing on a CPU?
* @p: the task in question.
+ *
+ * Return: 1 if the task is currently executing. 0 otherwise.
*/
inline int task_curr(const struct task_struct *p)
{
@@ -1482,7 +1484,7 @@ static void ttwu_queue(struct task_struct *p, int cpu)
* the simpler "current->state = TASK_RUNNING" to mark yourself
* runnable without the overhead of this.
*
- * Returns %true if @p was woken up, %false if it was already running
+ * Return: %true if @p was woken up, %false if it was already running.
* or @state didn't match @p's state.
*/
static int
@@ -1577,8 +1579,9 @@ out:
* @p: The process to be woken up.
*
* Attempt to wake up the nominated process and move it to the set of runnable
- * processes. Returns 1 if the process was woken up, 0 if it was already
- * running.
+ * processes.
+ *
+ * Return: 1 if the process was woken up, 0 if it was already running.
*
* It may be assumed that this function implies a write memory barrier before
* changing the task state if and only if any tasks are woken up.
@@ -2191,6 +2194,8 @@ void scheduler_tick(void)
* This makes sure that uptime, CFS vruntime, load
* balancing, etc... continue to move forward, even
* with a very low granularity.
+ *
+ * Return: Maximum deferment in nanoseconds.
*/
u64 scheduler_tick_max_deferment(void)
{
@@ -2796,8 +2801,8 @@ EXPORT_SYMBOL(wait_for_completion);
* specified timeout to expire. The timeout is in jiffies. It is not
* interruptible.
*
- * The return value is 0 if timed out, and positive (at least 1, or number of
- * jiffies left till timeout) if completed.
+ * Return: 0 if timed out, and positive (at least 1, or number of jiffies left
+ * till timeout) if completed.
*/
unsigned long __sched
wait_for_completion_timeout(struct completion *x, unsigned long timeout)
@@ -2829,8 +2834,8 @@ EXPORT_SYMBOL(wait_for_completion_io);
* specified timeout to expire. The timeout is in jiffies. It is not
* interruptible. The caller is accounted as waiting for IO.
*
- * The return value is 0 if timed out, and positive (at least 1, or number of
- * jiffies left till timeout) if completed.
+ * Return: 0 if timed out, and positive (at least 1, or number of jiffies left
+ * till timeout) if completed.
*/
unsigned long __sched
wait_for_completion_io_timeout(struct completion *x, unsigned long timeout)
@@ -2846,7 +2851,7 @@ EXPORT_SYMBOL(wait_for_completion_io_timeout);
* This waits for completion of a specific task to be signaled. It is
* interruptible.
*
- * The retur
[tip:sched/urgent] sched: Fix some kernel-doc warnings
Commit-ID: e69f61862ab833e9b8d3c15b6ce07fd69f3bfecc
Gitweb: http://git.kernel.org/tip/e69f61862ab833e9b8d3c15b6ce07fd69f3bfecc
Author: Yacine Belkadi yacine.belkad...@gmail.com
AuthorDate: Fri, 12 Jul 2013 20:45:47 +0200
Committer: Ingo Molnar mi...@kernel.org
CommitDate: Thu, 18 Jul 2013 09:58:21 +0200
sched: Fix some kernel-doc warnings
When building the htmldocs (in verbose mode), scripts/kernel-doc
reports the follwing type of warnings:
Warning(kernel/sched/core.c:936): No description found for return value of
'task_curr'
...
Fix those by:
- adding the missing descriptions
- using Return sections for the descriptions
Signed-off-by: Yacine Belkadi yacine.belkad...@gmail.com
Cc: Peter Zijlstra pet...@infradead.org
Link:
http://lkml.kernel.org/r/1373654747-2389-1-git-send-email-yacine.belkad...@gmail.com
[ While at it, fix the cpupri_set() explanation. ]
Signed-off-by: Ingo Molnar mi...@kernel.org
---
include/linux/sched.h | 6
kernel/sched/core.c | 82 ++-
kernel/sched/cpupri.c | 4 +--
kernel/sched/fair.c | 9 --
4 files changed, 76 insertions(+), 25 deletions(-)
diff --git a/include/linux/sched.h b/include/linux/sched.h
index 50d04b9..8230024 100644
--- a/include/linux/sched.h
+++ b/include/linux/sched.h
@@ -1532,6 +1532,8 @@ static inline pid_t task_pgrp_nr(struct task_struct *tsk)
* Test if a process is not yet dead (at most zombie state)
* If pid_alive fails, then pointers within the task structure
* can be stale and must not be dereferenced.
+ *
+ * Return: 1 if the process is alive. 0 otherwise.
*/
static inline int pid_alive(struct task_struct *p)
{
@@ -1543,6 +1545,8 @@ static inline int pid_alive(struct task_struct *p)
* @tsk: Task structure to be checked.
*
* Check if a task structure is the first user space task the kernel created.
+ *
+ * Return: 1 if the task structure is init. 0 otherwise.
*/
static inline int is_global_init(struct task_struct *tsk)
{
@@ -1893,6 +1897,8 @@ extern struct task_struct *idle_task(int cpu);
/**
* is_idle_task - is the specified task an idle task?
* @p: the task in question.
+ *
+ * Return: 1 if @p is an idle task. 0 otherwise.
*/
static inline bool is_idle_task(const struct task_struct *p)
{
diff --git a/kernel/sched/core.c b/kernel/sched/core.c
index 0d8eb45..4c3967f 100644
--- a/kernel/sched/core.c
+++ b/kernel/sched/core.c
@@ -933,6 +933,8 @@ static int effective_prio(struct task_struct *p)
/**
* task_curr - is this task currently executing on a CPU?
* @p: the task in question.
+ *
+ * Return: 1 if the task is currently executing. 0 otherwise.
*/
inline int task_curr(const struct task_struct *p)
{
@@ -1482,7 +1484,7 @@ static void ttwu_queue(struct task_struct *p, int cpu)
* the simpler current-state = TASK_RUNNING to mark yourself
* runnable without the overhead of this.
*
- * Returns %true if @p was woken up, %false if it was already running
+ * Return: %true if @p was woken up, %false if it was already running.
* or @state didn't match @p's state.
*/
static int
@@ -1577,8 +1579,9 @@ out:
* @p: The process to be woken up.
*
* Attempt to wake up the nominated process and move it to the set of runnable
- * processes. Returns 1 if the process was woken up, 0 if it was already
- * running.
+ * processes.
+ *
+ * Return: 1 if the process was woken up, 0 if it was already running.
*
* It may be assumed that this function implies a write memory barrier before
* changing the task state if and only if any tasks are woken up.
@@ -2191,6 +2194,8 @@ void scheduler_tick(void)
* This makes sure that uptime, CFS vruntime, load
* balancing, etc... continue to move forward, even
* with a very low granularity.
+ *
+ * Return: Maximum deferment in nanoseconds.
*/
u64 scheduler_tick_max_deferment(void)
{
@@ -2796,8 +2801,8 @@ EXPORT_SYMBOL(wait_for_completion);
* specified timeout to expire. The timeout is in jiffies. It is not
* interruptible.
*
- * The return value is 0 if timed out, and positive (at least 1, or number of
- * jiffies left till timeout) if completed.
+ * Return: 0 if timed out, and positive (at least 1, or number of jiffies left
+ * till timeout) if completed.
*/
unsigned long __sched
wait_for_completion_timeout(struct completion *x, unsigned long timeout)
@@ -2829,8 +2834,8 @@ EXPORT_SYMBOL(wait_for_completion_io);
* specified timeout to expire. The timeout is in jiffies. It is not
* interruptible. The caller is accounted as waiting for IO.
*
- * The return value is 0 if timed out, and positive (at least 1, or number of
- * jiffies left till timeout) if completed.
+ * Return: 0 if timed out, and positive (at least 1, or number of jiffies left
+ * till timeout) if completed.
*/
unsigned long __sched
wait_for_completion_io_timeout(struct completion *x, unsigned long timeout)
@@ -2846,7 +2851,7 @@ EXPORT_SYMBOL(wait_for_completion_io_timeout);
* This waits for completion
[PATCH] hrtimer, timer: fix some scripts/kernel-doc warnings
When building the htmldocs (in verbose mode), scripts/kernel-doc reports the
following type of warnings:
Warning(kernel/timer.c:230): No description found for return value of
'round_jiffies'
Fix them by:
- Using Return: sections to introduce the descriptions of return values.
- Adding missing descriptions.
Signed-off-by: Yacine Belkadi yacine.belkad...@gmail.com
---
Applied to d2b4a646717153a1a180b64d4a8464054dbd700e
kernel/hrtimer.c | 27 +--
kernel/timer.c | 40 ++--
2 files changed, 47 insertions(+), 20 deletions(-)
diff --git a/kernel/hrtimer.c b/kernel/hrtimer.c
index f0f4fe2..89696c9 100644
--- a/kernel/hrtimer.c
+++ b/kernel/hrtimer.c
@@ -277,7 +277,7 @@ lock_hrtimer_base(const struct hrtimer *timer, unsigned
long *flags)
* @kt:addend
* @nsec: the scalar nsec value to add
*
- * Returns the sum of kt and nsec in ktime_t format
+ * Return: The sum of @kt and @nsec in ktime_t format.
*/
ktime_t ktime_add_ns(const ktime_t kt, u64 nsec)
{
@@ -305,7 +305,7 @@ EXPORT_SYMBOL_GPL(ktime_add_ns);
* @kt:minuend
* @nsec: the scalar nsec value to subtract
*
- * Returns the subtraction of @nsec from @kt in ktime_t format
+ * Return: The subtraction of @nsec from @kt in ktime_t format.
*/
ktime_t ktime_sub_ns(const ktime_t kt, u64 nsec)
{
@@ -836,7 +836,8 @@ void unlock_hrtimer_base(const struct hrtimer *timer,
unsigned long *flags)
* @interval: the interval to forward
*
* Forward the timer expiry so it will expire in the future.
- * Returns the number of overruns.
+ *
+ * Return: The number of overruns.
*/
u64 hrtimer_forward(struct hrtimer *timer, ktime_t now, ktime_t interval)
{
@@ -1038,7 +1039,7 @@ int __hrtimer_start_range_ns(struct hrtimer *timer,
ktime_t tim,
* @mode: expiry mode: absolute (HRTIMER_MODE_ABS) or
* relative (HRTIMER_MODE_REL)
*
- * Returns:
+ * Return:
* 0 on success
* 1 when the timer was active
*/
@@ -1056,7 +1057,7 @@ EXPORT_SYMBOL_GPL(hrtimer_start_range_ns);
* @mode: expiry mode: absolute (HRTIMER_MODE_ABS) or
* relative (HRTIMER_MODE_REL)
*
- * Returns:
+ * Return:
* 0 on success
* 1 when the timer was active
*/
@@ -1072,7 +1073,7 @@ EXPORT_SYMBOL_GPL(hrtimer_start);
* hrtimer_try_to_cancel - try to deactivate a timer
* @timer: hrtimer to stop
*
- * Returns:
+ * Return:
* 0 when the timer was not active
* 1 when the timer was active
* -1 when the timer is currently excuting the callback function and
@@ -1100,7 +1101,7 @@ EXPORT_SYMBOL_GPL(hrtimer_try_to_cancel);
* hrtimer_cancel - cancel a timer and wait for the handler to finish.
* @timer: the timer to be cancelled
*
- * Returns:
+ * Return:
* 0 when the timer was not active
* 1 when the timer was active
*/
@@ -1119,6 +1120,8 @@ EXPORT_SYMBOL_GPL(hrtimer_cancel);
/**
* hrtimer_get_remaining - get remaining time for the timer
* @timer: the timer to read
+ *
+ * Return: The remaining time for @timer.
*/
ktime_t hrtimer_get_remaining(const struct hrtimer *timer)
{
@@ -1137,7 +1140,7 @@ EXPORT_SYMBOL_GPL(hrtimer_get_remaining);
/**
* hrtimer_get_next_event - get the time until next expiry event
*
- * Returns the delta to the next expiry event or KTIME_MAX if no timer
+ * Return: The delta to the next expiry event or KTIME_MAX if no timer
* is pending.
*/
ktime_t hrtimer_get_next_event(void)
@@ -1220,6 +1223,8 @@ EXPORT_SYMBOL_GPL(hrtimer_init);
*
* Store the resolution of the clock selected by @which_clock in the
* variable pointed to by @tp.
+ *
+ * Return: 0
*/
int hrtimer_get_res(const clockid_t which_clock, struct timespec *tp)
{
@@ -1793,6 +1798,8 @@ void __init hrtimers_init(void)
* @delta: slack in expires timeout (ktime_t)
* @mode: timer mode, HRTIMER_MODE_ABS or HRTIMER_MODE_REL
* @clock: timer clock, CLOCK_MONOTONIC or CLOCK_REALTIME
+ *
+ * Return: 0 when the timer has expired. Otherwise -EINTR.
*/
int __sched
schedule_hrtimeout_range_clock(ktime_t *expires, unsigned long delta,
@@ -1864,7 +1871,7 @@ schedule_hrtimeout_range_clock(ktime_t *expires, unsigned
long delta,
* The current task state is guaranteed to be TASK_RUNNING when this
* routine returns.
*
- * Returns 0 when the timer has expired otherwise -EINTR
+ * Return: 0 when the timer has expired. Otherwise -EINTR.
*/
int __sched schedule_hrtimeout_range(ktime_t *expires, unsigned long delta,
const enum hrtimer_mode mode)
@@ -1894,7 +1901,7 @@ EXPORT_SYMBOL_GPL(schedule_hrtimeout_range);
* The current task state is guaranteed to be TASK_RUNNING when this
* routine returns.
*
- * Returns 0 when the timer has expired otherwise -EINTR
+ * Return: 0 when the timer has expired. Otherwise -EINTR.
*/
int __sched schedule_hrtimeout(ktime_t *expires,
const enum hrtimer_mode mode)
diff --git
[PATCH] ktime: fix some scripts/kernel-doc warnings
When building the htmldocs (in verbose mode), scripts/kernel-doc reports the
following type of warnings:
Warning(include/linux/ktime.h:75): No description found for return value of
'ktime_set'
Fix them by using a "Return:" section to describe the return values.
(Also apply some minor reformatting along the way.)
Signed-off-by: Yacine Belkadi
---
Applied to d2b4a646717153a1a180b64d4a8464054dbd700e
include/linux/ktime.h | 28 +++-
1 file changed, 15 insertions(+), 13 deletions(-)
diff --git a/include/linux/ktime.h b/include/linux/ktime.h
index fc66b30..6e89f28 100644
--- a/include/linux/ktime.h
+++ b/include/linux/ktime.h
@@ -69,7 +69,7 @@ typedef union ktime ktime_t; /* Kill this */
* @secs: seconds to set
* @nsecs: nanoseconds to set
*
- * Return the ktime_t representation of the value
+ * Return: The ktime_t representation of the value.
*/
static inline ktime_t ktime_set(const long secs, const unsigned long nsecs)
{
@@ -151,7 +151,7 @@ static inline ktime_t ktime_set(const long secs, const
unsigned long nsecs)
* @lhs: minuend
* @rhs: subtrahend
*
- * Returns the remainder of the subtraction
+ * Return: The remainder of the subtraction.
*/
static inline ktime_t ktime_sub(const ktime_t lhs, const ktime_t rhs)
{
@@ -169,7 +169,7 @@ static inline ktime_t ktime_sub(const ktime_t lhs, const
ktime_t rhs)
* @add1: addend1
* @add2: addend2
*
- * Returns the sum of @add1 and @add2.
+ * Return: The sum of @add1 and @add2.
*/
static inline ktime_t ktime_add(const ktime_t add1, const ktime_t add2)
{
@@ -195,7 +195,7 @@ static inline ktime_t ktime_add(const ktime_t add1, const
ktime_t add2)
* @kt:addend
* @nsec: the scalar nsec value to add
*
- * Returns the sum of @kt and @nsec in ktime_t format
+ * Return: The sum of @kt and @nsec in ktime_t format.
*/
extern ktime_t ktime_add_ns(const ktime_t kt, u64 nsec);
@@ -204,7 +204,7 @@ extern ktime_t ktime_add_ns(const ktime_t kt, u64 nsec);
* @kt:minuend
* @nsec: the scalar nsec value to subtract
*
- * Returns the subtraction of @nsec from @kt in ktime_t format
+ * Return: The subtraction of @nsec from @kt in ktime_t format.
*/
extern ktime_t ktime_sub_ns(const ktime_t kt, u64 nsec);
@@ -212,7 +212,7 @@ extern ktime_t ktime_sub_ns(const ktime_t kt, u64 nsec);
* timespec_to_ktime - convert a timespec to ktime_t format
* @ts:the timespec variable to convert
*
- * Returns a ktime_t variable with the converted timespec value
+ * Return: A ktime_t variable with the converted timespec value.
*/
static inline ktime_t timespec_to_ktime(const struct timespec ts)
{
@@ -224,7 +224,7 @@ static inline ktime_t timespec_to_ktime(const struct
timespec ts)
* timeval_to_ktime - convert a timeval to ktime_t format
* @tv:the timeval variable to convert
*
- * Returns a ktime_t variable with the converted timeval value
+ * Return: A ktime_t variable with the converted timeval value.
*/
static inline ktime_t timeval_to_ktime(const struct timeval tv)
{
@@ -237,7 +237,7 @@ static inline ktime_t timeval_to_ktime(const struct timeval
tv)
* ktime_to_timespec - convert a ktime_t variable to timespec format
* @kt:the ktime_t variable to convert
*
- * Returns the timespec representation of the ktime value
+ * Return: The timespec representation of the ktime value.
*/
static inline struct timespec ktime_to_timespec(const ktime_t kt)
{
@@ -249,7 +249,7 @@ static inline struct timespec ktime_to_timespec(const
ktime_t kt)
* ktime_to_timeval - convert a ktime_t variable to timeval format
* @kt:the ktime_t variable to convert
*
- * Returns the timeval representation of the ktime value
+ * Return: The timeval representation of the ktime value.
*/
static inline struct timeval ktime_to_timeval(const ktime_t kt)
{
@@ -262,7 +262,7 @@ static inline struct timeval ktime_to_timeval(const ktime_t
kt)
* ktime_to_ns - convert a ktime_t variable to scalar nanoseconds
* @kt:the ktime_t variable to convert
*
- * Returns the scalar nanoseconds representation of @kt
+ * Return: The scalar nanoseconds representation of @kt.
*/
static inline s64 ktime_to_ns(const ktime_t kt)
{
@@ -276,7 +276,9 @@ static inline s64 ktime_to_ns(const ktime_t kt)
* @cmp1: comparable1
* @cmp2: comparable2
*
- * Compare two ktime_t variables, returns 1 if equal
+ * Compare two ktime_t variables.
+ *
+ * Return: 1 if equal.
*/
static inline int ktime_equal(const ktime_t cmp1, const ktime_t cmp2)
{
@@ -288,7 +290,7 @@ static inline int ktime_equal(const ktime_t cmp1, const
ktime_t cmp2)
* @cmp1: comparable1
* @cmp2: comparable2
*
- * Returns ...
+ * Return: ...
* cmp1 < cmp2: return <0
* cmp1 == cmp2: return 0
* cmp1 > cmp2: return >0
@@ -337,7 +339,7 @@ extern ktime_t ktime_
[PATCH] ktime: fix some scripts/kernel-doc warnings
When building the htmldocs (in verbose mode), scripts/kernel-doc reports the
following type of warnings:
Warning(include/linux/ktime.h:75): No description found for return value of
'ktime_set'
Fix them by using a Return: section to describe the return values.
(Also apply some minor reformatting along the way.)
Signed-off-by: Yacine Belkadi yacine.belkad...@gmail.com
---
Applied to d2b4a646717153a1a180b64d4a8464054dbd700e
include/linux/ktime.h | 28 +++-
1 file changed, 15 insertions(+), 13 deletions(-)
diff --git a/include/linux/ktime.h b/include/linux/ktime.h
index fc66b30..6e89f28 100644
--- a/include/linux/ktime.h
+++ b/include/linux/ktime.h
@@ -69,7 +69,7 @@ typedef union ktime ktime_t; /* Kill this */
* @secs: seconds to set
* @nsecs: nanoseconds to set
*
- * Return the ktime_t representation of the value
+ * Return: The ktime_t representation of the value.
*/
static inline ktime_t ktime_set(const long secs, const unsigned long nsecs)
{
@@ -151,7 +151,7 @@ static inline ktime_t ktime_set(const long secs, const
unsigned long nsecs)
* @lhs: minuend
* @rhs: subtrahend
*
- * Returns the remainder of the subtraction
+ * Return: The remainder of the subtraction.
*/
static inline ktime_t ktime_sub(const ktime_t lhs, const ktime_t rhs)
{
@@ -169,7 +169,7 @@ static inline ktime_t ktime_sub(const ktime_t lhs, const
ktime_t rhs)
* @add1: addend1
* @add2: addend2
*
- * Returns the sum of @add1 and @add2.
+ * Return: The sum of @add1 and @add2.
*/
static inline ktime_t ktime_add(const ktime_t add1, const ktime_t add2)
{
@@ -195,7 +195,7 @@ static inline ktime_t ktime_add(const ktime_t add1, const
ktime_t add2)
* @kt:addend
* @nsec: the scalar nsec value to add
*
- * Returns the sum of @kt and @nsec in ktime_t format
+ * Return: The sum of @kt and @nsec in ktime_t format.
*/
extern ktime_t ktime_add_ns(const ktime_t kt, u64 nsec);
@@ -204,7 +204,7 @@ extern ktime_t ktime_add_ns(const ktime_t kt, u64 nsec);
* @kt:minuend
* @nsec: the scalar nsec value to subtract
*
- * Returns the subtraction of @nsec from @kt in ktime_t format
+ * Return: The subtraction of @nsec from @kt in ktime_t format.
*/
extern ktime_t ktime_sub_ns(const ktime_t kt, u64 nsec);
@@ -212,7 +212,7 @@ extern ktime_t ktime_sub_ns(const ktime_t kt, u64 nsec);
* timespec_to_ktime - convert a timespec to ktime_t format
* @ts:the timespec variable to convert
*
- * Returns a ktime_t variable with the converted timespec value
+ * Return: A ktime_t variable with the converted timespec value.
*/
static inline ktime_t timespec_to_ktime(const struct timespec ts)
{
@@ -224,7 +224,7 @@ static inline ktime_t timespec_to_ktime(const struct
timespec ts)
* timeval_to_ktime - convert a timeval to ktime_t format
* @tv:the timeval variable to convert
*
- * Returns a ktime_t variable with the converted timeval value
+ * Return: A ktime_t variable with the converted timeval value.
*/
static inline ktime_t timeval_to_ktime(const struct timeval tv)
{
@@ -237,7 +237,7 @@ static inline ktime_t timeval_to_ktime(const struct timeval
tv)
* ktime_to_timespec - convert a ktime_t variable to timespec format
* @kt:the ktime_t variable to convert
*
- * Returns the timespec representation of the ktime value
+ * Return: The timespec representation of the ktime value.
*/
static inline struct timespec ktime_to_timespec(const ktime_t kt)
{
@@ -249,7 +249,7 @@ static inline struct timespec ktime_to_timespec(const
ktime_t kt)
* ktime_to_timeval - convert a ktime_t variable to timeval format
* @kt:the ktime_t variable to convert
*
- * Returns the timeval representation of the ktime value
+ * Return: The timeval representation of the ktime value.
*/
static inline struct timeval ktime_to_timeval(const ktime_t kt)
{
@@ -262,7 +262,7 @@ static inline struct timeval ktime_to_timeval(const ktime_t
kt)
* ktime_to_ns - convert a ktime_t variable to scalar nanoseconds
* @kt:the ktime_t variable to convert
*
- * Returns the scalar nanoseconds representation of @kt
+ * Return: The scalar nanoseconds representation of @kt.
*/
static inline s64 ktime_to_ns(const ktime_t kt)
{
@@ -276,7 +276,9 @@ static inline s64 ktime_to_ns(const ktime_t kt)
* @cmp1: comparable1
* @cmp2: comparable2
*
- * Compare two ktime_t variables, returns 1 if equal
+ * Compare two ktime_t variables.
+ *
+ * Return: 1 if equal.
*/
static inline int ktime_equal(const ktime_t cmp1, const ktime_t cmp2)
{
@@ -288,7 +290,7 @@ static inline int ktime_equal(const ktime_t cmp1, const
ktime_t cmp2)
* @cmp1: comparable1
* @cmp2: comparable2
*
- * Returns ...
+ * Return: ...
* cmp1 cmp2: return 0
* cmp1 == cmp2: return 0
* cmp1 cmp2: return 0
@@ -337,7 +339,7 @@ extern ktime_t
[PATCH] sched: fix some kernel-doc warnings
When building the htmldocs (in verbose mode), scripts/kernel-doc reports the
follwing type of warnings:
Warning(kernel/sched/core.c:936): No description found for return value of
'task_curr'
Fix those by:
- adding the missing descriptions
- using "Return" sections for the descriptions
Signed-off-by: Yacine Belkadi
---
Applied to d2b4a646717153a1a180b64d4a8464054dbd700e
include/linux/sched.h |6
kernel/sched/core.c | 82 -
kernel/sched/cpupri.c |4 +--
kernel/sched/fair.c |9 --
4 files changed, 76 insertions(+), 25 deletions(-)
diff --git a/include/linux/sched.h b/include/linux/sched.h
index cdd5407..96720dd 100644
--- a/include/linux/sched.h
+++ b/include/linux/sched.h
@@ -1537,6 +1537,8 @@ static inline pid_t task_pgrp_nr(struct task_struct *tsk)
* Test if a process is not yet dead (at most zombie state)
* If pid_alive fails, then pointers within the task structure
* can be stale and must not be dereferenced.
+ *
+ * Return: 1 if the process is alive. 0 otherwise.
*/
static inline int pid_alive(struct task_struct *p)
{
@@ -1548,6 +1550,8 @@ static inline int pid_alive(struct task_struct *p)
* @tsk: Task structure to be checked.
*
* Check if a task structure is the first user space task the kernel created.
+ *
+ * Return: 1 if the task structure is init. 0 otherwise.
*/
static inline int is_global_init(struct task_struct *tsk)
{
@@ -1898,6 +1902,8 @@ extern struct task_struct *idle_task(int cpu);
/**
* is_idle_task - is the specified task an idle task?
* @p: the task in question.
+ *
+ * Return: 1 if @p is an idle task. 0 otherwise.
*/
static inline bool is_idle_task(const struct task_struct *p)
{
diff --git a/kernel/sched/core.c b/kernel/sched/core.c
index 9b1f2e5..cbbf574 100644
--- a/kernel/sched/core.c
+++ b/kernel/sched/core.c
@@ -931,6 +931,8 @@ static int effective_prio(struct task_struct *p)
/**
* task_curr - is this task currently executing on a CPU?
* @p: the task in question.
+ *
+ * Return: 1 if the task is currently executing. 0 otherwise.
*/
inline int task_curr(const struct task_struct *p)
{
@@ -1480,7 +1482,7 @@ static void ttwu_queue(struct task_struct *p, int cpu)
* the simpler "current->state = TASK_RUNNING" to mark yourself
* runnable without the overhead of this.
*
- * Returns %true if @p was woken up, %false if it was already running
+ * Return: %true if @p was woken up, %false if it was already running.
* or @state didn't match @p's state.
*/
static int
@@ -1575,8 +1577,9 @@ out:
* @p: The process to be woken up.
*
* Attempt to wake up the nominated process and move it to the set of runnable
- * processes. Returns 1 if the process was woken up, 0 if it was already
- * running.
+ * processes.
+ *
+ * Return: 1 if the process was woken up, 0 if it was already running.
*
* It may be assumed that this function implies a write memory barrier before
* changing the task state if and only if any tasks are woken up.
@@ -2189,6 +2192,8 @@ void scheduler_tick(void)
* This makes sure that uptime, CFS vruntime, load
* balancing, etc... continue to move forward, even
* with a very low granularity.
+ *
+ * Return: Maximum deferment in nanoseconds.
*/
u64 scheduler_tick_max_deferment(void)
{
@@ -2794,8 +2799,8 @@ EXPORT_SYMBOL(wait_for_completion);
* specified timeout to expire. The timeout is in jiffies. It is not
* interruptible.
*
- * The return value is 0 if timed out, and positive (at least 1, or number of
- * jiffies left till timeout) if completed.
+ * Return: 0 if timed out, and positive (at least 1, or number of jiffies left
+ * till timeout) if completed.
*/
unsigned long __sched
wait_for_completion_timeout(struct completion *x, unsigned long timeout)
@@ -2827,8 +2832,8 @@ EXPORT_SYMBOL(wait_for_completion_io);
* specified timeout to expire. The timeout is in jiffies. It is not
* interruptible. The caller is accounted as waiting for IO.
*
- * The return value is 0 if timed out, and positive (at least 1, or number of
- * jiffies left till timeout) if completed.
+ * Return: 0 if timed out, and positive (at least 1, or number of jiffies left
+ * till timeout) if completed.
*/
unsigned long __sched
wait_for_completion_io_timeout(struct completion *x, unsigned long timeout)
@@ -2844,7 +2849,7 @@ EXPORT_SYMBOL(wait_for_completion_io_timeout);
* This waits for completion of a specific task to be signaled. It is
* interruptible.
*
- * The return value is -ERESTARTSYS if interrupted, 0 if completed.
+ * Return: -ERESTARTSYS if interrupted, 0 if completed.
*/
int __sched wait_for_completion_interruptible(struct completion *x)
{
@@ -2863,8 +2868,8 @@ EXPORT_SYMBOL(wait_for_completion_interruptible);
* This waits for either a completion of a specific task to be signaled or for
a
* specified timeout to expire. It is interruptible. The timeout is in jiffies.
*
- * The return value is -ERE
[PATCH] sched: fix some kernel-doc warnings
When building the htmldocs (in verbose mode), scripts/kernel-doc reports the
follwing type of warnings:
Warning(kernel/sched/core.c:936): No description found for return value of
'task_curr'
Fix those by:
- adding the missing descriptions
- using Return sections for the descriptions
Signed-off-by: Yacine Belkadi yacine.belkad...@gmail.com
---
Applied to d2b4a646717153a1a180b64d4a8464054dbd700e
include/linux/sched.h |6
kernel/sched/core.c | 82 -
kernel/sched/cpupri.c |4 +--
kernel/sched/fair.c |9 --
4 files changed, 76 insertions(+), 25 deletions(-)
diff --git a/include/linux/sched.h b/include/linux/sched.h
index cdd5407..96720dd 100644
--- a/include/linux/sched.h
+++ b/include/linux/sched.h
@@ -1537,6 +1537,8 @@ static inline pid_t task_pgrp_nr(struct task_struct *tsk)
* Test if a process is not yet dead (at most zombie state)
* If pid_alive fails, then pointers within the task structure
* can be stale and must not be dereferenced.
+ *
+ * Return: 1 if the process is alive. 0 otherwise.
*/
static inline int pid_alive(struct task_struct *p)
{
@@ -1548,6 +1550,8 @@ static inline int pid_alive(struct task_struct *p)
* @tsk: Task structure to be checked.
*
* Check if a task structure is the first user space task the kernel created.
+ *
+ * Return: 1 if the task structure is init. 0 otherwise.
*/
static inline int is_global_init(struct task_struct *tsk)
{
@@ -1898,6 +1902,8 @@ extern struct task_struct *idle_task(int cpu);
/**
* is_idle_task - is the specified task an idle task?
* @p: the task in question.
+ *
+ * Return: 1 if @p is an idle task. 0 otherwise.
*/
static inline bool is_idle_task(const struct task_struct *p)
{
diff --git a/kernel/sched/core.c b/kernel/sched/core.c
index 9b1f2e5..cbbf574 100644
--- a/kernel/sched/core.c
+++ b/kernel/sched/core.c
@@ -931,6 +931,8 @@ static int effective_prio(struct task_struct *p)
/**
* task_curr - is this task currently executing on a CPU?
* @p: the task in question.
+ *
+ * Return: 1 if the task is currently executing. 0 otherwise.
*/
inline int task_curr(const struct task_struct *p)
{
@@ -1480,7 +1482,7 @@ static void ttwu_queue(struct task_struct *p, int cpu)
* the simpler current-state = TASK_RUNNING to mark yourself
* runnable without the overhead of this.
*
- * Returns %true if @p was woken up, %false if it was already running
+ * Return: %true if @p was woken up, %false if it was already running.
* or @state didn't match @p's state.
*/
static int
@@ -1575,8 +1577,9 @@ out:
* @p: The process to be woken up.
*
* Attempt to wake up the nominated process and move it to the set of runnable
- * processes. Returns 1 if the process was woken up, 0 if it was already
- * running.
+ * processes.
+ *
+ * Return: 1 if the process was woken up, 0 if it was already running.
*
* It may be assumed that this function implies a write memory barrier before
* changing the task state if and only if any tasks are woken up.
@@ -2189,6 +2192,8 @@ void scheduler_tick(void)
* This makes sure that uptime, CFS vruntime, load
* balancing, etc... continue to move forward, even
* with a very low granularity.
+ *
+ * Return: Maximum deferment in nanoseconds.
*/
u64 scheduler_tick_max_deferment(void)
{
@@ -2794,8 +2799,8 @@ EXPORT_SYMBOL(wait_for_completion);
* specified timeout to expire. The timeout is in jiffies. It is not
* interruptible.
*
- * The return value is 0 if timed out, and positive (at least 1, or number of
- * jiffies left till timeout) if completed.
+ * Return: 0 if timed out, and positive (at least 1, or number of jiffies left
+ * till timeout) if completed.
*/
unsigned long __sched
wait_for_completion_timeout(struct completion *x, unsigned long timeout)
@@ -2827,8 +2832,8 @@ EXPORT_SYMBOL(wait_for_completion_io);
* specified timeout to expire. The timeout is in jiffies. It is not
* interruptible. The caller is accounted as waiting for IO.
*
- * The return value is 0 if timed out, and positive (at least 1, or number of
- * jiffies left till timeout) if completed.
+ * Return: 0 if timed out, and positive (at least 1, or number of jiffies left
+ * till timeout) if completed.
*/
unsigned long __sched
wait_for_completion_io_timeout(struct completion *x, unsigned long timeout)
@@ -2844,7 +2849,7 @@ EXPORT_SYMBOL(wait_for_completion_io_timeout);
* This waits for completion of a specific task to be signaled. It is
* interruptible.
*
- * The return value is -ERESTARTSYS if interrupted, 0 if completed.
+ * Return: -ERESTARTSYS if interrupted, 0 if completed.
*/
int __sched wait_for_completion_interruptible(struct completion *x)
{
@@ -2863,8 +2868,8 @@ EXPORT_SYMBOL(wait_for_completion_interruptible);
* This waits for either a completion of a specific task to be signaled or for
a
* specified timeout to expire. It is interruptible. The timeout is in jiffies.
*
- * The return value
Re: [PATCH] {cfg,mac}80211.h: fix some kernel-doc warnings
Hi, On 01/16/2013 03:11 PM, Johannes Berg wrote: > Hi, > > I totally missed your email before. > >> Warning(include/net/cfg80211.h:334): No description found for return value >> of 'cfg80211_get_chandef_type' >> >> These warnings are only reported when scripts/kernel-doc runs in verbose >> mode. >> >> Fix: >> In comments, use "Return:" to describe function return values. > > I wasn't even aware of this, is that new? Anyway, applied, thanks. Yes, it's from December. Here is the last thread: https://lkml.org/lkml/2012/11/26/709 Yacine -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH] {cfg,mac}80211.h: fix some kernel-doc warnings
Hi, On 01/16/2013 03:11 PM, Johannes Berg wrote: Hi, I totally missed your email before. Warning(include/net/cfg80211.h:334): No description found for return value of 'cfg80211_get_chandef_type' These warnings are only reported when scripts/kernel-doc runs in verbose mode. Fix: In comments, use Return: to describe function return values. I wasn't even aware of this, is that new? Anyway, applied, thanks. Yes, it's from December. Here is the last thread: https://lkml.org/lkml/2012/11/26/709 Yacine -- To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
[PATCH] {cfg,mac}80211.h: fix some kernel-doc warnings
When building the 80211 DocBook, scripts/kernel-doc reports the following type
of warnings:
Warning(include/net/cfg80211.h:334): No description found for return value of
'cfg80211_get_chandef_type'
These warnings are only reported when scripts/kernel-doc runs in verbose mode.
Fix:
In comments, use "Return:" to describe function return values.
Signed-off-by: Yacine Belkadi
---
include/net/cfg80211.h | 154
include/net/mac80211.h | 74 ++-
2 files changed, 151 insertions(+), 77 deletions(-)
diff --git a/include/net/cfg80211.h b/include/net/cfg80211.h
index 8e6a6b7..9f2f585 100644
--- a/include/net/cfg80211.h
+++ b/include/net/cfg80211.h
@@ -326,7 +326,7 @@ struct cfg80211_chan_def {
* cfg80211_get_chandef_type - return old channel type from chandef
* @chandef: the channel definition
*
- * Returns the old channel type (NOHT, HT20, HT40+/-) from a given
+ * Return: The old channel type (NOHT, HT20, HT40+/-) from a given
* chandef, which must have a bandwidth allowing this conversion.
*/
static inline enum nl80211_channel_type
@@ -364,7 +364,7 @@ void cfg80211_chandef_create(struct cfg80211_chan_def
*chandef,
* @chandef1: first channel definition
* @chandef2: second channel definition
*
- * Returns %true if the channels defined by the channel definitions are
+ * Return: %true if the channels defined by the channel definitions are
* identical, %false otherwise.
*/
static inline bool
@@ -382,7 +382,7 @@ cfg80211_chandef_identical(const struct cfg80211_chan_def
*chandef1,
* @chandef1: first channel definition
* @chandef2: second channel definition
*
- * Returns %NULL if the given channel definitions are incompatible,
+ * Return: %NULL if the given channel definitions are incompatible,
* chandef1 or chandef2 otherwise.
*/
const struct cfg80211_chan_def *
@@ -392,6 +392,7 @@ cfg80211_chandef_compatible(const struct cfg80211_chan_def
*chandef1,
/**
* cfg80211_chandef_valid - check if a channel definition is valid
* @chandef: the channel definition to check
+ * Return: %true if the channel definition is valid. %false otherwise.
*/
bool cfg80211_chandef_valid(const struct cfg80211_chan_def *chandef);
@@ -399,7 +400,8 @@ bool cfg80211_chandef_valid(const struct cfg80211_chan_def
*chandef);
* cfg80211_chandef_usable - check if secondary channels can be used
* @wiphy: the wiphy to validate against
* @chandef: the channel definition to check
- * @prohibited_flags: the regulatory chanenl flags that must not be set
+ * @prohibited_flags: the regulatory channel flags that must not be set
+ * Return: %true if secondary channels are usable. %false otherwise.
*/
bool cfg80211_chandef_usable(struct wiphy *wiphy,
const struct cfg80211_chan_def *chandef,
@@ -1266,7 +1268,7 @@ struct cfg80211_bss {
*
* Note that the return value is an RCU-protected pointer, so
* rcu_read_lock() must be held when calling this function.
- * Returns %NULL if not found.
+ * Return: %NULL if not found.
*/
const u8 *ieee80211_bss_get_ie(struct cfg80211_bss *bss, u8 ie);
@@ -2409,6 +2411,7 @@ static inline void wiphy_net_set(struct wiphy *wiphy,
struct net *net)
* wiphy_priv - return priv from wiphy
*
* @wiphy: the wiphy whose priv pointer to return
+ * Return: The priv of @wiphy.
*/
static inline void *wiphy_priv(struct wiphy *wiphy)
{
@@ -2420,6 +2423,7 @@ static inline void *wiphy_priv(struct wiphy *wiphy)
* priv_to_wiphy - return the wiphy containing the priv
*
* @priv: a pointer previously returned by wiphy_priv
+ * Return: The wiphy of @priv.
*/
static inline struct wiphy *priv_to_wiphy(void *priv)
{
@@ -2442,6 +2446,7 @@ static inline void set_wiphy_dev(struct wiphy *wiphy,
struct device *dev)
* wiphy_dev - get wiphy dev pointer
*
* @wiphy: The wiphy whose device struct to look up
+ * Return: The dev of @wiphy.
*/
static inline struct device *wiphy_dev(struct wiphy *wiphy)
{
@@ -2452,6 +2457,7 @@ static inline struct device *wiphy_dev(struct wiphy
*wiphy)
* wiphy_name - get wiphy name
*
* @wiphy: The wiphy whose name to return
+ * Return: The name of @wiphy.
*/
static inline const char *wiphy_name(const struct wiphy *wiphy)
{
@@ -2467,8 +2473,8 @@ static inline const char *wiphy_name(const struct wiphy
*wiphy)
* Create a new wiphy and associate the given operations with it.
* @sizeof_priv bytes are allocated for private use.
*
- * The returned pointer must be assigned to each netdev's
- * ieee80211_ptr for proper operation.
+ * Return: A pointer to the new wiphy. This pointer must be
+ * assigned to each netdev's ieee80211_ptr for proper operation.
*/
struct wiphy *wiphy_new(const struct cfg80211_ops *ops, int sizeof_priv);
@@ -2477,7 +2483,7 @@ struct wiphy *wiphy_new(const struct cfg80211_ops *ops,
int sizeof_priv);
*
* @wiphy: The wiphy to register.
*
- * Returns a non-negative wiphy index or
[PATCH] {cfg,mac}80211.h: fix some kernel-doc warnings
When building the 80211 DocBook, scripts/kernel-doc reports the following type
of warnings:
Warning(include/net/cfg80211.h:334): No description found for return value of
'cfg80211_get_chandef_type'
These warnings are only reported when scripts/kernel-doc runs in verbose mode.
Fix:
In comments, use Return: to describe function return values.
Signed-off-by: Yacine Belkadi yacine.belkad...@gmail.com
---
include/net/cfg80211.h | 154
include/net/mac80211.h | 74 ++-
2 files changed, 151 insertions(+), 77 deletions(-)
diff --git a/include/net/cfg80211.h b/include/net/cfg80211.h
index 8e6a6b7..9f2f585 100644
--- a/include/net/cfg80211.h
+++ b/include/net/cfg80211.h
@@ -326,7 +326,7 @@ struct cfg80211_chan_def {
* cfg80211_get_chandef_type - return old channel type from chandef
* @chandef: the channel definition
*
- * Returns the old channel type (NOHT, HT20, HT40+/-) from a given
+ * Return: The old channel type (NOHT, HT20, HT40+/-) from a given
* chandef, which must have a bandwidth allowing this conversion.
*/
static inline enum nl80211_channel_type
@@ -364,7 +364,7 @@ void cfg80211_chandef_create(struct cfg80211_chan_def
*chandef,
* @chandef1: first channel definition
* @chandef2: second channel definition
*
- * Returns %true if the channels defined by the channel definitions are
+ * Return: %true if the channels defined by the channel definitions are
* identical, %false otherwise.
*/
static inline bool
@@ -382,7 +382,7 @@ cfg80211_chandef_identical(const struct cfg80211_chan_def
*chandef1,
* @chandef1: first channel definition
* @chandef2: second channel definition
*
- * Returns %NULL if the given channel definitions are incompatible,
+ * Return: %NULL if the given channel definitions are incompatible,
* chandef1 or chandef2 otherwise.
*/
const struct cfg80211_chan_def *
@@ -392,6 +392,7 @@ cfg80211_chandef_compatible(const struct cfg80211_chan_def
*chandef1,
/**
* cfg80211_chandef_valid - check if a channel definition is valid
* @chandef: the channel definition to check
+ * Return: %true if the channel definition is valid. %false otherwise.
*/
bool cfg80211_chandef_valid(const struct cfg80211_chan_def *chandef);
@@ -399,7 +400,8 @@ bool cfg80211_chandef_valid(const struct cfg80211_chan_def
*chandef);
* cfg80211_chandef_usable - check if secondary channels can be used
* @wiphy: the wiphy to validate against
* @chandef: the channel definition to check
- * @prohibited_flags: the regulatory chanenl flags that must not be set
+ * @prohibited_flags: the regulatory channel flags that must not be set
+ * Return: %true if secondary channels are usable. %false otherwise.
*/
bool cfg80211_chandef_usable(struct wiphy *wiphy,
const struct cfg80211_chan_def *chandef,
@@ -1266,7 +1268,7 @@ struct cfg80211_bss {
*
* Note that the return value is an RCU-protected pointer, so
* rcu_read_lock() must be held when calling this function.
- * Returns %NULL if not found.
+ * Return: %NULL if not found.
*/
const u8 *ieee80211_bss_get_ie(struct cfg80211_bss *bss, u8 ie);
@@ -2409,6 +2411,7 @@ static inline void wiphy_net_set(struct wiphy *wiphy,
struct net *net)
* wiphy_priv - return priv from wiphy
*
* @wiphy: the wiphy whose priv pointer to return
+ * Return: The priv of @wiphy.
*/
static inline void *wiphy_priv(struct wiphy *wiphy)
{
@@ -2420,6 +2423,7 @@ static inline void *wiphy_priv(struct wiphy *wiphy)
* priv_to_wiphy - return the wiphy containing the priv
*
* @priv: a pointer previously returned by wiphy_priv
+ * Return: The wiphy of @priv.
*/
static inline struct wiphy *priv_to_wiphy(void *priv)
{
@@ -2442,6 +2446,7 @@ static inline void set_wiphy_dev(struct wiphy *wiphy,
struct device *dev)
* wiphy_dev - get wiphy dev pointer
*
* @wiphy: The wiphy whose device struct to look up
+ * Return: The dev of @wiphy.
*/
static inline struct device *wiphy_dev(struct wiphy *wiphy)
{
@@ -2452,6 +2457,7 @@ static inline struct device *wiphy_dev(struct wiphy
*wiphy)
* wiphy_name - get wiphy name
*
* @wiphy: The wiphy whose name to return
+ * Return: The name of @wiphy.
*/
static inline const char *wiphy_name(const struct wiphy *wiphy)
{
@@ -2467,8 +2473,8 @@ static inline const char *wiphy_name(const struct wiphy
*wiphy)
* Create a new wiphy and associate the given operations with it.
* @sizeof_priv bytes are allocated for private use.
*
- * The returned pointer must be assigned to each netdev's
- * ieee80211_ptr for proper operation.
+ * Return: A pointer to the new wiphy. This pointer must be
+ * assigned to each netdev's ieee80211_ptr for proper operation.
*/
struct wiphy *wiphy_new(const struct cfg80211_ops *ops, int sizeof_priv);
@@ -2477,7 +2483,7 @@ struct wiphy *wiphy_new(const struct cfg80211_ops *ops,
int sizeof_priv);
*
* @wiphy: The wiphy to register.
*
- * Returns a non-negative
[PATCHv2 2/2] scripts/kernel-doc: check that non-void fcts describe their return value
If a function has a return value, but its kernel-doc comment doesn't contain a
"Return" section, then emit the following warning:
Warning(file.h:129): No description found for return value of 'fct'
Note: This check emits a lot of warnings at the moment, because many functions
don't have a 'Return' doc section. So until the number of warnings goes
sufficiently down, the check is only performed in verbose mode.
Signed-off-by: Yacine Belkadi
---
scripts/kernel-doc | 34 ++
1 file changed, 34 insertions(+)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 46e7aff..28b7615 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -137,6 +137,8 @@ use strict;
# should document the "Context:" of the function, e.g. whether the functions
# can be called form interrupts. Unlike other sections you can end it with an
# empty line.
+# A non-void function should have a "Return:" section describing the return
+# value(s).
# Example-sections should contain the string EXAMPLE so that they are marked
# appropriately in DocBook.
#
@@ -315,6 +317,7 @@ my $section_default = "Description";# default
section
my $section_intro = "Introduction";
my $section = $section_default;
my $section_context = "Context";
+my $section_return = "Return";
my $undescribed = "-- undescribed --";
@@ -2039,6 +2042,28 @@ sub check_sections($$) {
}
##
+# Checks the section describing the return value of a function.
+sub check_return_section {
+my $file = shift;
+my $declaration_name = shift;
+my $return_type = shift;
+
+# Ignore an empty return type (It's a macro)
+# Ignore functions with a "void" return type. (But don't ignore "void
*")
+if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
+return;
+}
+
+if (!defined($sections{$section_return}) ||
+$sections{$section_return} eq "") {
+print STDERR "Warning(${file}:$.): " .
+"No description found for return value of " .
+"'$declaration_name'\n";
+++$warnings;
+}
+}
+
+##
# takes a function prototype and the name of the current file being
# processed and spits out all the details stored in the global
# arrays/hashes.
@@ -2109,6 +2134,15 @@ sub dump_function($$) {
my $prms = join " ", @parameterlist;
check_sections($file, $declaration_name, "function", $sectcheck, $prms,
"");
+# This check emits a lot of warnings at the moment, because many
+# functions don't have a 'Return' doc section. So until the number
+# of warnings goes sufficiently down, the check is only performed in
+# verbose mode.
+# TODO: always perform the check.
+if ($verbose) {
+check_return_section($file, $declaration_name, $return_type);
+}
+
output_declaration($declaration_name,
'function',
{'function' => $declaration_name,
--
1.7.9.5
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
[PATCHv2 1/2] Kernel-doc: Convention: Use a "Return" section to describe return values
Non-void functions should describe their return values in their kernel-doc comments. Currently, some don't, others do in various forms. For example: * Return the result. * Return: The result. * Returns the result. * Returns: the result. * Return Value: The result. * @return: the result. * This function returns the result. * It will return the result. Defining a convention would improve consistency of kernel-doc comments. It would also help scripts/kernel-doc identify the text describing the return value of a function. Thus allowing additional checks on the comments, and suitable highlighting in the generated docs (man pages, html, etc). So, as a convention, use a section named "Return" to describe the return value of a function. Signed-off-by: Yacine Belkadi --- Documentation/kernel-doc-nano-HOWTO.txt | 13 ++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt index 3d8a977..99b57ab 100644 --- a/Documentation/kernel-doc-nano-HOWTO.txt +++ b/Documentation/kernel-doc-nano-HOWTO.txt @@ -64,6 +64,8 @@ Example kernel-doc function comment: * comment lines. * * The longer description can have multiple paragraphs. + * + * Return: Describe the return value of foobar. */ The short description following the subject can span multiple lines @@ -78,6 +80,8 @@ If a function parameter is "..." (varargs), it should be listed in kernel-doc notation as: * @...: description +The return value, if any, should be described in a dedicated section +named "Return". Example kernel-doc data structure comment. @@ -222,6 +226,9 @@ only a "*"). "section header:" names must be unique per function (or struct, union, typedef, enum). +Use the section header "Return" for sections describing the return value +of a function. + Avoid putting a spurious blank line after the function name, or else the description will be repeated! @@ -237,21 +244,21 @@ patterns, which are highlighted appropriately. NOTE 1: The multi-line descriptive text you provide does *not* recognize line breaks, so if you try to format some text nicely, as in: - Return codes + Return: 0 - cool 1 - invalid arg 2 - out of memory this will all run together and produce: - Return codes 0 - cool 1 - invalid arg 2 - out of memory + Return: 0 - cool 1 - invalid arg 2 - out of memory NOTE 2: If the descriptive text you provide has lines that begin with some phrase followed by a colon, each of those phrases will be taken as a new section heading, which means you should similarly try to avoid text like: - Return codes: + Return: 0: cool 1: invalid arg 2: out of memory -- 1.7.9.5 -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
[PATCHv2 1/2] Kernel-doc: Convention: Use a Return section to describe return values
Non-void functions should describe their return values in their kernel-doc comments. Currently, some don't, others do in various forms. For example: * Return the result. * Return: The result. * Returns the result. * Returns: the result. * Return Value: The result. * @return: the result. * This function returns the result. * It will return the result. Defining a convention would improve consistency of kernel-doc comments. It would also help scripts/kernel-doc identify the text describing the return value of a function. Thus allowing additional checks on the comments, and suitable highlighting in the generated docs (man pages, html, etc). So, as a convention, use a section named Return to describe the return value of a function. Signed-off-by: Yacine Belkadi yacine.belkad...@gmail.com --- Documentation/kernel-doc-nano-HOWTO.txt | 13 ++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt index 3d8a977..99b57ab 100644 --- a/Documentation/kernel-doc-nano-HOWTO.txt +++ b/Documentation/kernel-doc-nano-HOWTO.txt @@ -64,6 +64,8 @@ Example kernel-doc function comment: * comment lines. * * The longer description can have multiple paragraphs. + * + * Return: Describe the return value of foobar. */ The short description following the subject can span multiple lines @@ -78,6 +80,8 @@ If a function parameter is ... (varargs), it should be listed in kernel-doc notation as: * @...: description +The return value, if any, should be described in a dedicated section +named Return. Example kernel-doc data structure comment. @@ -222,6 +226,9 @@ only a *). section header: names must be unique per function (or struct, union, typedef, enum). +Use the section header Return for sections describing the return value +of a function. + Avoid putting a spurious blank line after the function name, or else the description will be repeated! @@ -237,21 +244,21 @@ patterns, which are highlighted appropriately. NOTE 1: The multi-line descriptive text you provide does *not* recognize line breaks, so if you try to format some text nicely, as in: - Return codes + Return: 0 - cool 1 - invalid arg 2 - out of memory this will all run together and produce: - Return codes 0 - cool 1 - invalid arg 2 - out of memory + Return: 0 - cool 1 - invalid arg 2 - out of memory NOTE 2: If the descriptive text you provide has lines that begin with some phrase followed by a colon, each of those phrases will be taken as a new section heading, which means you should similarly try to avoid text like: - Return codes: + Return: 0: cool 1: invalid arg 2: out of memory -- 1.7.9.5 -- To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
[PATCHv2 2/2] scripts/kernel-doc: check that non-void fcts describe their return value
If a function has a return value, but its kernel-doc comment doesn't contain a
Return section, then emit the following warning:
Warning(file.h:129): No description found for return value of 'fct'
Note: This check emits a lot of warnings at the moment, because many functions
don't have a 'Return' doc section. So until the number of warnings goes
sufficiently down, the check is only performed in verbose mode.
Signed-off-by: Yacine Belkadi yacine.belkad...@gmail.com
---
scripts/kernel-doc | 34 ++
1 file changed, 34 insertions(+)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 46e7aff..28b7615 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -137,6 +137,8 @@ use strict;
# should document the Context: of the function, e.g. whether the functions
# can be called form interrupts. Unlike other sections you can end it with an
# empty line.
+# A non-void function should have a Return: section describing the return
+# value(s).
# Example-sections should contain the string EXAMPLE so that they are marked
# appropriately in DocBook.
#
@@ -315,6 +317,7 @@ my $section_default = Description;# default
section
my $section_intro = Introduction;
my $section = $section_default;
my $section_context = Context;
+my $section_return = Return;
my $undescribed = -- undescribed --;
@@ -2039,6 +2042,28 @@ sub check_sections($$) {
}
##
+# Checks the section describing the return value of a function.
+sub check_return_section {
+my $file = shift;
+my $declaration_name = shift;
+my $return_type = shift;
+
+# Ignore an empty return type (It's a macro)
+# Ignore functions with a void return type. (But don't ignore void
*)
+if (($return_type eq ) || ($return_type =~ /void\s*\w*\s*$/)) {
+return;
+}
+
+if (!defined($sections{$section_return}) ||
+$sections{$section_return} eq ) {
+print STDERR Warning(${file}:$.): .
+No description found for return value of .
+'$declaration_name'\n;
+++$warnings;
+}
+}
+
+##
# takes a function prototype and the name of the current file being
# processed and spits out all the details stored in the global
# arrays/hashes.
@@ -2109,6 +2134,15 @@ sub dump_function($$) {
my $prms = join , @parameterlist;
check_sections($file, $declaration_name, function, $sectcheck, $prms,
);
+# This check emits a lot of warnings at the moment, because many
+# functions don't have a 'Return' doc section. So until the number
+# of warnings goes sufficiently down, the check is only performed in
+# verbose mode.
+# TODO: always perform the check.
+if ($verbose) {
+check_return_section($file, $declaration_name, $return_type);
+}
+
output_declaration($declaration_name,
'function',
{'function' = $declaration_name,
--
1.7.9.5
--
To unsubscribe from this list: send the line unsubscribe linux-kernel in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
[PATCHv2 2/2] scripts/kernel-doc: check that non-void fcts describe their return value
If a function has a return value, but its kernel-doc comment doesn't contain a
"Return" section, then emit the following warning:
Warning(file.h:129): No description found for return value of 'fct'
Note: This check emits a lot of warnings at the moment, because many functions
don't have a 'Return' doc section. So until the number of warnings goes
sufficiently down, the check is only performed in verbose mode.
Signed-off-by: Yacine Belkadi
---
scripts/kernel-doc | 34 ++
1 file changed, 34 insertions(+)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 46e7aff..28b7615 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -137,6 +137,8 @@ use strict;
# should document the "Context:" of the function, e.g. whether the functions
# can be called form interrupts. Unlike other sections you can end it with an
# empty line.
+# A non-void function should have a "Return:" section describing the return
+# value(s).
# Example-sections should contain the string EXAMPLE so that they are marked
# appropriately in DocBook.
#
@@ -315,6 +317,7 @@ my $section_default = "Description";# default
section
my $section_intro = "Introduction";
my $section = $section_default;
my $section_context = "Context";
+my $section_return = "Return";
my $undescribed = "-- undescribed --";
@@ -2039,6 +2042,28 @@ sub check_sections($$) {
}
##
+# Checks the section describing the return value of a function.
+sub check_return_section {
+my $file = shift;
+my $declaration_name = shift;
+my $return_type = shift;
+
+# Ignore an empty return type (It's a macro)
+# Ignore functions with a "void" return type. (But don't ignore "void
*")
+if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
+return;
+}
+
+if (!defined($sections{$section_return}) ||
+$sections{$section_return} eq "") {
+print STDERR "Warning(${file}:$.): " .
+"No description found for return value of " .
+"'$declaration_name'\n";
+++$warnings;
+}
+}
+
+##
# takes a function prototype and the name of the current file being
# processed and spits out all the details stored in the global
# arrays/hashes.
@@ -2109,6 +2134,15 @@ sub dump_function($$) {
my $prms = join " ", @parameterlist;
check_sections($file, $declaration_name, "function", $sectcheck, $prms,
"");
+# This check emits a lot of warnings at the moment, because many
+# functions don't have a 'Return' doc section. So until the number
+# of warnings goes sufficiently down, the check is only performed in
+# verbose mode.
+# TODO: always perform the check.
+if ($verbose) {
+check_return_section($file, $declaration_name, $return_type);
+}
+
output_declaration($declaration_name,
'function',
{'function' => $declaration_name,
--
1.7.9.5
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
[PATCHv2 1/2] Kernel-doc: Convention: Use a "Return" section to describe return values
Non-void functions should describe their return values in their kernel-doc comments. Currently, some don't, others do in various forms. For example: * Return the result. * Return: The result. * Returns the result. * Returns: the result. * Return Value: The result. * @return: the result. * This function returns the result. * It will return the result. Defining a convention would improve consistency of kernel-doc comments. It would also help scripts/kernel-doc identify the text describing the return value of a function. Thus allowing additional checks on the comments, and suitable highlighting in the generated docs (man pages, html, etc). So, as a convention, use a section named "Return" to describe the return value of a function. Signed-off-by: Yacine Belkadi --- Documentation/kernel-doc-nano-HOWTO.txt | 13 ++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt index 3d8a977..99b57ab 100644 --- a/Documentation/kernel-doc-nano-HOWTO.txt +++ b/Documentation/kernel-doc-nano-HOWTO.txt @@ -64,6 +64,8 @@ Example kernel-doc function comment: * comment lines. * * The longer description can have multiple paragraphs. + * + * Return: Describe the return value of foobar. */ The short description following the subject can span multiple lines @@ -78,6 +80,8 @@ If a function parameter is "..." (varargs), it should be listed in kernel-doc notation as: * @...: description +The return value, if any, should be described in a dedicated section +named "Return". Example kernel-doc data structure comment. @@ -222,6 +226,9 @@ only a "*"). "section header:" names must be unique per function (or struct, union, typedef, enum). +Use the section header "Return" for sections describing the return value +of a function. + Avoid putting a spurious blank line after the function name, or else the description will be repeated! @@ -237,21 +244,21 @@ patterns, which are highlighted appropriately. NOTE 1: The multi-line descriptive text you provide does *not* recognize line breaks, so if you try to format some text nicely, as in: - Return codes + Return: 0 - cool 1 - invalid arg 2 - out of memory this will all run together and produce: - Return codes 0 - cool 1 - invalid arg 2 - out of memory + Return: 0 - cool 1 - invalid arg 2 - out of memory NOTE 2: If the descriptive text you provide has lines that begin with some phrase followed by a colon, each of those phrases will be taken as a new section heading, which means you should similarly try to avoid text like: - Return codes: + Return: 0: cool 1: invalid arg 2: out of memory -- 1.7.9.5 -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
[PATCHv2 1/2] Kernel-doc: Convention: Use a Return section to describe return values
Non-void functions should describe their return values in their kernel-doc comments. Currently, some don't, others do in various forms. For example: * Return the result. * Return: The result. * Returns the result. * Returns: the result. * Return Value: The result. * @return: the result. * This function returns the result. * It will return the result. Defining a convention would improve consistency of kernel-doc comments. It would also help scripts/kernel-doc identify the text describing the return value of a function. Thus allowing additional checks on the comments, and suitable highlighting in the generated docs (man pages, html, etc). So, as a convention, use a section named Return to describe the return value of a function. Signed-off-by: Yacine Belkadi yacine.belkad...@gmail.com --- Documentation/kernel-doc-nano-HOWTO.txt | 13 ++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt index 3d8a977..99b57ab 100644 --- a/Documentation/kernel-doc-nano-HOWTO.txt +++ b/Documentation/kernel-doc-nano-HOWTO.txt @@ -64,6 +64,8 @@ Example kernel-doc function comment: * comment lines. * * The longer description can have multiple paragraphs. + * + * Return: Describe the return value of foobar. */ The short description following the subject can span multiple lines @@ -78,6 +80,8 @@ If a function parameter is ... (varargs), it should be listed in kernel-doc notation as: * @...: description +The return value, if any, should be described in a dedicated section +named Return. Example kernel-doc data structure comment. @@ -222,6 +226,9 @@ only a *). section header: names must be unique per function (or struct, union, typedef, enum). +Use the section header Return for sections describing the return value +of a function. + Avoid putting a spurious blank line after the function name, or else the description will be repeated! @@ -237,21 +244,21 @@ patterns, which are highlighted appropriately. NOTE 1: The multi-line descriptive text you provide does *not* recognize line breaks, so if you try to format some text nicely, as in: - Return codes + Return: 0 - cool 1 - invalid arg 2 - out of memory this will all run together and produce: - Return codes 0 - cool 1 - invalid arg 2 - out of memory + Return: 0 - cool 1 - invalid arg 2 - out of memory NOTE 2: If the descriptive text you provide has lines that begin with some phrase followed by a colon, each of those phrases will be taken as a new section heading, which means you should similarly try to avoid text like: - Return codes: + Return: 0: cool 1: invalid arg 2: out of memory -- 1.7.9.5 -- To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
[PATCHv2 2/2] scripts/kernel-doc: check that non-void fcts describe their return value
If a function has a return value, but its kernel-doc comment doesn't contain a
Return section, then emit the following warning:
Warning(file.h:129): No description found for return value of 'fct'
Note: This check emits a lot of warnings at the moment, because many functions
don't have a 'Return' doc section. So until the number of warnings goes
sufficiently down, the check is only performed in verbose mode.
Signed-off-by: Yacine Belkadi yacine.belkad...@gmail.com
---
scripts/kernel-doc | 34 ++
1 file changed, 34 insertions(+)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 46e7aff..28b7615 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -137,6 +137,8 @@ use strict;
# should document the Context: of the function, e.g. whether the functions
# can be called form interrupts. Unlike other sections you can end it with an
# empty line.
+# A non-void function should have a Return: section describing the return
+# value(s).
# Example-sections should contain the string EXAMPLE so that they are marked
# appropriately in DocBook.
#
@@ -315,6 +317,7 @@ my $section_default = Description;# default
section
my $section_intro = Introduction;
my $section = $section_default;
my $section_context = Context;
+my $section_return = Return;
my $undescribed = -- undescribed --;
@@ -2039,6 +2042,28 @@ sub check_sections($$) {
}
##
+# Checks the section describing the return value of a function.
+sub check_return_section {
+my $file = shift;
+my $declaration_name = shift;
+my $return_type = shift;
+
+# Ignore an empty return type (It's a macro)
+# Ignore functions with a void return type. (But don't ignore void
*)
+if (($return_type eq ) || ($return_type =~ /void\s*\w*\s*$/)) {
+return;
+}
+
+if (!defined($sections{$section_return}) ||
+$sections{$section_return} eq ) {
+print STDERR Warning(${file}:$.): .
+No description found for return value of .
+'$declaration_name'\n;
+++$warnings;
+}
+}
+
+##
# takes a function prototype and the name of the current file being
# processed and spits out all the details stored in the global
# arrays/hashes.
@@ -2109,6 +2134,15 @@ sub dump_function($$) {
my $prms = join , @parameterlist;
check_sections($file, $declaration_name, function, $sectcheck, $prms,
);
+# This check emits a lot of warnings at the moment, because many
+# functions don't have a 'Return' doc section. So until the number
+# of warnings goes sufficiently down, the check is only performed in
+# verbose mode.
+# TODO: always perform the check.
+if ($verbose) {
+check_return_section($file, $declaration_name, $return_type);
+}
+
output_declaration($declaration_name,
'function',
{'function' = $declaration_name,
--
1.7.9.5
--
To unsubscribe from this list: send the line unsubscribe linux-kernel in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
[PATCH 2/2] scripts/kernel-doc: check that non-void fcts describe their return value
If a function has a return value, but its kernel-doc comment doesn't contain a
"Return" section, then emit the following warning:
Warning(file.h:129): No description found for return value of 'fct'
Note: This check emits a lot of warnings at the moment, because many functions
don't have a 'Return' doc section. So until the number of warnings goes
sufficiently down, the check is only performed in verbose mode.
Signed-off-by: Yacine Belkadi
---
scripts/kernel-doc | 34 ++
1 file changed, 34 insertions(+)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 8fd107a..7f82aa8 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -130,6 +130,8 @@ use strict;
# should document the "Context:" of the function, e.g. whether the functions
# can be called form interrupts. Unlike other sections you can end it with an
# empty line.
+# A non-void function should have a "Return:" section describing the return
+# value.
# Example-sections should contain the string EXAMPLE so that they are marked
# appropriately in DocBook.
#
@@ -298,6 +300,7 @@ my $section_default = "Description";# default
section
my $section_intro = "Introduction";
my $section = $section_default;
my $section_context = "Context";
+my $section_return = "Return";
my $undescribed = "-- undescribed --";
@@ -1767,6 +1770,28 @@ sub check_sections($$) {
}
##
+# Checks the section describing the return value of a function.
+sub check_return_section {
+my $file = shift;
+my $declaration_name = shift;
+my $return_type = shift;
+
+# Ignore an empty return type (It's a macro)
+# Ignore functions with a "void" return type. (But don't ignore "void
*")
+if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
+return;
+}
+
+if (!defined($sections{$section_return}) ||
+$sections{$section_return} eq "") {
+print STDERR "Warning(${file}:$.): " .
+"No description found for return value of " .
+"'$declaration_name'\n";
+++$warnings;
+}
+}
+
+##
# takes a function prototype and the name of the current file being
# processed and spits out all the details stored in the global
# arrays/hashes.
@@ -1837,6 +1862,15 @@ sub dump_function($$) {
my $prms = join " ", @parameterlist;
check_sections($file, $declaration_name, "function", $sectcheck, $prms,
"");
+# This check emits a lot of warnings at the moment, because many
+# functions don't have a 'Return' doc section. So until the number
+# of warnings goes sufficiently down, the check is only performed in
+# verbose mode.
+# TODO: always perform the check.
+if ($verbose) {
+check_return_section($file, $declaration_name, $return_type);
+}
+
output_declaration($declaration_name,
'function',
{'function' => $declaration_name,
--
1.7.9.5
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
[PATCH 1/2] Kernel-doc: Convention: Use a "Return" section to describe return values
Non-void functions should describe their return values in their kernel-doc comments. Currently, some don't, others do in various forms. For example: * Return the result. * Return: The result. * Returns the result. * Returns: the result. * Return Value: The result. * @return: the result. * This function returns the result. * It will return the result. Defining a convention would improve consistency of kernel-doc comments. It would also help scripts/kernel-doc identify the text describing the return value of a function. Thus allowing additional checks on the comments, and suitable highlighting in the generated docs (man pages, html, etc). So, as a convention, use a section named "Return" to describe the return value of a function. Signed-off-by: Yacine Belkadi --- Documentation/kernel-doc-nano-HOWTO.txt | 13 ++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt index 3d8a977..99b57ab 100644 --- a/Documentation/kernel-doc-nano-HOWTO.txt +++ b/Documentation/kernel-doc-nano-HOWTO.txt @@ -64,6 +64,8 @@ Example kernel-doc function comment: * comment lines. * * The longer description can have multiple paragraphs. + * + * Return: Describe the return value of foobar. */ The short description following the subject can span multiple lines @@ -78,6 +80,8 @@ If a function parameter is "..." (varargs), it should be listed in kernel-doc notation as: * @...: description +The return value, if any, should be described in a dedicated section +named "Return". Example kernel-doc data structure comment. @@ -222,6 +226,9 @@ only a "*"). "section header:" names must be unique per function (or struct, union, typedef, enum). +Use the section header "Return" for sections describing the return value +of a function. + Avoid putting a spurious blank line after the function name, or else the description will be repeated! @@ -237,21 +244,21 @@ patterns, which are highlighted appropriately. NOTE 1: The multi-line descriptive text you provide does *not* recognize line breaks, so if you try to format some text nicely, as in: - Return codes + Return: 0 - cool 1 - invalid arg 2 - out of memory this will all run together and produce: - Return codes 0 - cool 1 - invalid arg 2 - out of memory + Return: 0 - cool 1 - invalid arg 2 - out of memory NOTE 2: If the descriptive text you provide has lines that begin with some phrase followed by a colon, each of those phrases will be taken as a new section heading, which means you should similarly try to avoid text like: - Return codes: + Return: 0: cool 1: invalid arg 2: out of memory -- 1.7.9.5 -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
[PATCH 1/2] Kernel-doc: Convention: Use a Return section to describe return values
Non-void functions should describe their return values in their kernel-doc comments. Currently, some don't, others do in various forms. For example: * Return the result. * Return: The result. * Returns the result. * Returns: the result. * Return Value: The result. * @return: the result. * This function returns the result. * It will return the result. Defining a convention would improve consistency of kernel-doc comments. It would also help scripts/kernel-doc identify the text describing the return value of a function. Thus allowing additional checks on the comments, and suitable highlighting in the generated docs (man pages, html, etc). So, as a convention, use a section named Return to describe the return value of a function. Signed-off-by: Yacine Belkadi yacine.belkad...@gmail.com --- Documentation/kernel-doc-nano-HOWTO.txt | 13 ++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt index 3d8a977..99b57ab 100644 --- a/Documentation/kernel-doc-nano-HOWTO.txt +++ b/Documentation/kernel-doc-nano-HOWTO.txt @@ -64,6 +64,8 @@ Example kernel-doc function comment: * comment lines. * * The longer description can have multiple paragraphs. + * + * Return: Describe the return value of foobar. */ The short description following the subject can span multiple lines @@ -78,6 +80,8 @@ If a function parameter is ... (varargs), it should be listed in kernel-doc notation as: * @...: description +The return value, if any, should be described in a dedicated section +named Return. Example kernel-doc data structure comment. @@ -222,6 +226,9 @@ only a *). section header: names must be unique per function (or struct, union, typedef, enum). +Use the section header Return for sections describing the return value +of a function. + Avoid putting a spurious blank line after the function name, or else the description will be repeated! @@ -237,21 +244,21 @@ patterns, which are highlighted appropriately. NOTE 1: The multi-line descriptive text you provide does *not* recognize line breaks, so if you try to format some text nicely, as in: - Return codes + Return: 0 - cool 1 - invalid arg 2 - out of memory this will all run together and produce: - Return codes 0 - cool 1 - invalid arg 2 - out of memory + Return: 0 - cool 1 - invalid arg 2 - out of memory NOTE 2: If the descriptive text you provide has lines that begin with some phrase followed by a colon, each of those phrases will be taken as a new section heading, which means you should similarly try to avoid text like: - Return codes: + Return: 0: cool 1: invalid arg 2: out of memory -- 1.7.9.5 -- To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
[PATCH 2/2] scripts/kernel-doc: check that non-void fcts describe their return value
If a function has a return value, but its kernel-doc comment doesn't contain a
Return section, then emit the following warning:
Warning(file.h:129): No description found for return value of 'fct'
Note: This check emits a lot of warnings at the moment, because many functions
don't have a 'Return' doc section. So until the number of warnings goes
sufficiently down, the check is only performed in verbose mode.
Signed-off-by: Yacine Belkadi yacine.belkad...@gmail.com
---
scripts/kernel-doc | 34 ++
1 file changed, 34 insertions(+)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 8fd107a..7f82aa8 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -130,6 +130,8 @@ use strict;
# should document the Context: of the function, e.g. whether the functions
# can be called form interrupts. Unlike other sections you can end it with an
# empty line.
+# A non-void function should have a Return: section describing the return
+# value.
# Example-sections should contain the string EXAMPLE so that they are marked
# appropriately in DocBook.
#
@@ -298,6 +300,7 @@ my $section_default = Description;# default
section
my $section_intro = Introduction;
my $section = $section_default;
my $section_context = Context;
+my $section_return = Return;
my $undescribed = -- undescribed --;
@@ -1767,6 +1770,28 @@ sub check_sections($$) {
}
##
+# Checks the section describing the return value of a function.
+sub check_return_section {
+my $file = shift;
+my $declaration_name = shift;
+my $return_type = shift;
+
+# Ignore an empty return type (It's a macro)
+# Ignore functions with a void return type. (But don't ignore void
*)
+if (($return_type eq ) || ($return_type =~ /void\s*\w*\s*$/)) {
+return;
+}
+
+if (!defined($sections{$section_return}) ||
+$sections{$section_return} eq ) {
+print STDERR Warning(${file}:$.): .
+No description found for return value of .
+'$declaration_name'\n;
+++$warnings;
+}
+}
+
+##
# takes a function prototype and the name of the current file being
# processed and spits out all the details stored in the global
# arrays/hashes.
@@ -1837,6 +1862,15 @@ sub dump_function($$) {
my $prms = join , @parameterlist;
check_sections($file, $declaration_name, function, $sectcheck, $prms,
);
+# This check emits a lot of warnings at the moment, because many
+# functions don't have a 'Return' doc section. So until the number
+# of warnings goes sufficiently down, the check is only performed in
+# verbose mode.
+# TODO: always perform the check.
+if ($verbose) {
+check_return_section($file, $declaration_name, $return_type);
+}
+
output_declaration($declaration_name,
'function',
{'function' = $declaration_name,
--
1.7.9.5
--
To unsubscribe from this list: send the line unsubscribe linux-kernel in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
[PATCH RFC 2/2] scripts/kernel-doc: check that non-void fcts describe their return value
If a function has a return value, but its kernel-doc comment doesn't contain a
"Return" section, then emit the following warning:
Warning(file.h:129): No description found for return value of 'fct'
Note: This check emits a lot of warnings at the moment, because many functions
don't have a 'Return' doc section. So until the number of warnings goes
sufficiently down, the check is only performed in verbose mode.
Signed-off-by: Yacine Belkadi
---
scripts/kernel-doc | 34 ++
1 file changed, 34 insertions(+)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 8fd107a..7f82aa8 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -130,6 +130,8 @@ use strict;
# should document the "Context:" of the function, e.g. whether the functions
# can be called form interrupts. Unlike other sections you can end it with an
# empty line.
+# A non-void function should have a "Return:" section describing the return
+# value.
# Example-sections should contain the string EXAMPLE so that they are marked
# appropriately in DocBook.
#
@@ -298,6 +300,7 @@ my $section_default = "Description";# default
section
my $section_intro = "Introduction";
my $section = $section_default;
my $section_context = "Context";
+my $section_return = "Return";
my $undescribed = "-- undescribed --";
@@ -1767,6 +1770,28 @@ sub check_sections($$) {
}
##
+# Checks the section describing the return value of a function.
+sub check_return_section {
+my $file = shift;
+my $declaration_name = shift;
+my $return_type = shift;
+
+# Ignore an empty return type (It's a macro)
+# Ignore functions with a "void" return type. (But don't ignore "void
*")
+if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
+return;
+}
+
+if (!defined($sections{$section_return}) ||
+$sections{$section_return} eq "") {
+print STDERR "Warning(${file}:$.): " .
+"No description found for return value of " .
+"'$declaration_name'\n";
+++$warnings;
+}
+}
+
+##
# takes a function prototype and the name of the current file being
# processed and spits out all the details stored in the global
# arrays/hashes.
@@ -1837,6 +1862,15 @@ sub dump_function($$) {
my $prms = join " ", @parameterlist;
check_sections($file, $declaration_name, "function", $sectcheck, $prms,
"");
+# This check emits a lot of warnings at the moment, because many
+# functions don't have a 'Return' doc section. So until the number
+# of warnings goes sufficiently down, the check is only performed in
+# verbose mode.
+# TODO: always perform the check.
+if ($verbose) {
+check_return_section($file, $declaration_name, $return_type);
+}
+
output_declaration($declaration_name,
'function',
{'function' => $declaration_name,
--
1.7.9.5
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
[PATCH RFC 1/2] Kernel-doc: Convention: Use a "Return" section to describe return values
Non-void functions should describe their return values in their kernel-doc comments. Currently, some don't, others do in various forms. For example: * Return the result. * Return: The result. * Returns the result. * Returns: the result. * Return Value: The result. * @return: the result. * This function returns the result. * It will return the result. Defining a convention would improve consistency of kernel-doc comments. It would also help scripts/kernel-doc identify the text describing the return value of a function. Thus allowing additional checks on the comments, and suitable highlighting in the generated docs (man pages, html, etc). So, as a convention, use a section named "Return" to describe the return value of a function. Signed-off-by: Yacine Belkadi --- Documentation/kernel-doc-nano-HOWTO.txt | 13 ++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt index 3d8a977..99b57ab 100644 --- a/Documentation/kernel-doc-nano-HOWTO.txt +++ b/Documentation/kernel-doc-nano-HOWTO.txt @@ -64,6 +64,8 @@ Example kernel-doc function comment: * comment lines. * * The longer description can have multiple paragraphs. + * + * Return: Describe the return value of foobar. */ The short description following the subject can span multiple lines @@ -78,6 +80,8 @@ If a function parameter is "..." (varargs), it should be listed in kernel-doc notation as: * @...: description +The return value, if any, should be described in a dedicated section +named "Return". Example kernel-doc data structure comment. @@ -222,6 +226,9 @@ only a "*"). "section header:" names must be unique per function (or struct, union, typedef, enum). +Use the section header "Return" for sections describing the return value +of a function. + Avoid putting a spurious blank line after the function name, or else the description will be repeated! @@ -237,21 +244,21 @@ patterns, which are highlighted appropriately. NOTE 1: The multi-line descriptive text you provide does *not* recognize line breaks, so if you try to format some text nicely, as in: - Return codes + Return: 0 - cool 1 - invalid arg 2 - out of memory this will all run together and produce: - Return codes 0 - cool 1 - invalid arg 2 - out of memory + Return: 0 - cool 1 - invalid arg 2 - out of memory NOTE 2: If the descriptive text you provide has lines that begin with some phrase followed by a colon, each of those phrases will be taken as a new section heading, which means you should similarly try to avoid text like: - Return codes: + Return: 0: cool 1: invalid arg 2: out of memory -- 1.7.9.5 -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
[PATCH RFC 1/2] Kernel-doc: Convention: Use a Return section to describe return values
Non-void functions should describe their return values in their kernel-doc comments. Currently, some don't, others do in various forms. For example: * Return the result. * Return: The result. * Returns the result. * Returns: the result. * Return Value: The result. * @return: the result. * This function returns the result. * It will return the result. Defining a convention would improve consistency of kernel-doc comments. It would also help scripts/kernel-doc identify the text describing the return value of a function. Thus allowing additional checks on the comments, and suitable highlighting in the generated docs (man pages, html, etc). So, as a convention, use a section named Return to describe the return value of a function. Signed-off-by: Yacine Belkadi yacine.belkad...@gmail.com --- Documentation/kernel-doc-nano-HOWTO.txt | 13 ++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt index 3d8a977..99b57ab 100644 --- a/Documentation/kernel-doc-nano-HOWTO.txt +++ b/Documentation/kernel-doc-nano-HOWTO.txt @@ -64,6 +64,8 @@ Example kernel-doc function comment: * comment lines. * * The longer description can have multiple paragraphs. + * + * Return: Describe the return value of foobar. */ The short description following the subject can span multiple lines @@ -78,6 +80,8 @@ If a function parameter is ... (varargs), it should be listed in kernel-doc notation as: * @...: description +The return value, if any, should be described in a dedicated section +named Return. Example kernel-doc data structure comment. @@ -222,6 +226,9 @@ only a *). section header: names must be unique per function (or struct, union, typedef, enum). +Use the section header Return for sections describing the return value +of a function. + Avoid putting a spurious blank line after the function name, or else the description will be repeated! @@ -237,21 +244,21 @@ patterns, which are highlighted appropriately. NOTE 1: The multi-line descriptive text you provide does *not* recognize line breaks, so if you try to format some text nicely, as in: - Return codes + Return: 0 - cool 1 - invalid arg 2 - out of memory this will all run together and produce: - Return codes 0 - cool 1 - invalid arg 2 - out of memory + Return: 0 - cool 1 - invalid arg 2 - out of memory NOTE 2: If the descriptive text you provide has lines that begin with some phrase followed by a colon, each of those phrases will be taken as a new section heading, which means you should similarly try to avoid text like: - Return codes: + Return: 0: cool 1: invalid arg 2: out of memory -- 1.7.9.5 -- To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
[PATCH RFC 2/2] scripts/kernel-doc: check that non-void fcts describe their return value
If a function has a return value, but its kernel-doc comment doesn't contain a
Return section, then emit the following warning:
Warning(file.h:129): No description found for return value of 'fct'
Note: This check emits a lot of warnings at the moment, because many functions
don't have a 'Return' doc section. So until the number of warnings goes
sufficiently down, the check is only performed in verbose mode.
Signed-off-by: Yacine Belkadi yacine.belkad...@gmail.com
---
scripts/kernel-doc | 34 ++
1 file changed, 34 insertions(+)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 8fd107a..7f82aa8 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -130,6 +130,8 @@ use strict;
# should document the Context: of the function, e.g. whether the functions
# can be called form interrupts. Unlike other sections you can end it with an
# empty line.
+# A non-void function should have a Return: section describing the return
+# value.
# Example-sections should contain the string EXAMPLE so that they are marked
# appropriately in DocBook.
#
@@ -298,6 +300,7 @@ my $section_default = Description;# default
section
my $section_intro = Introduction;
my $section = $section_default;
my $section_context = Context;
+my $section_return = Return;
my $undescribed = -- undescribed --;
@@ -1767,6 +1770,28 @@ sub check_sections($$) {
}
##
+# Checks the section describing the return value of a function.
+sub check_return_section {
+my $file = shift;
+my $declaration_name = shift;
+my $return_type = shift;
+
+# Ignore an empty return type (It's a macro)
+# Ignore functions with a void return type. (But don't ignore void
*)
+if (($return_type eq ) || ($return_type =~ /void\s*\w*\s*$/)) {
+return;
+}
+
+if (!defined($sections{$section_return}) ||
+$sections{$section_return} eq ) {
+print STDERR Warning(${file}:$.): .
+No description found for return value of .
+'$declaration_name'\n;
+++$warnings;
+}
+}
+
+##
# takes a function prototype and the name of the current file being
# processed and spits out all the details stored in the global
# arrays/hashes.
@@ -1837,6 +1862,15 @@ sub dump_function($$) {
my $prms = join , @parameterlist;
check_sections($file, $declaration_name, function, $sectcheck, $prms,
);
+# This check emits a lot of warnings at the moment, because many
+# functions don't have a 'Return' doc section. So until the number
+# of warnings goes sufficiently down, the check is only performed in
+# verbose mode.
+# TODO: always perform the check.
+if ($verbose) {
+check_return_section($file, $declaration_name, $return_type);
+}
+
output_declaration($declaration_name,
'function',
{'function' = $declaration_name,
--
1.7.9.5
--
To unsubscribe from this list: send the line unsubscribe linux-kernel in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
