[PATCH] ktime/hrtimer: fix kernel-doc comments

[PATCH] ktime/hrtimer: fix kernel-doc comments

[Randy.Dunlap]

From: Randy Dunlap <rdunlap@xenotime.net>

Fix kernel-doc formatting in ktime.h and hrtimer.[ch] files.

Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
---
 include/linux/hrtimer.h |    3 ---
 include/linux/ktime.h   |    8 --------
 kernel/hrtimer.c        |   11 +----------
 3 files changed, 1 insertion(+), 21 deletions(-)

--- linux-2617-pv.orig/include/linux/ktime.h
+++ linux-2617-pv/include/linux/ktime.h
@@ -66,7 +66,6 @@ typedef union {
 
 /**
  * ktime_set - Set a ktime_t variable from a seconds/nanoseconds value
- *
  * @secs:	seconds to set
  * @nsecs:	nanoseconds to set
  *
@@ -138,7 +137,6 @@ static inline ktime_t ktime_set(const lo
 
 /**
  * ktime_sub - subtract two ktime_t variables
- *
  * @lhs:	minuend
  * @rhs:	subtrahend
  *
@@ -157,7 +155,6 @@ static inline ktime_t ktime_sub(const kt
 
 /**
  * ktime_add - add two ktime_t variables
- *
  * @add1:	addend1
  * @add2:	addend2
  *
@@ -184,7 +181,6 @@ static inline ktime_t ktime_add(const kt
 
 /**
  * ktime_add_ns - Add a scalar nanoseconds value to a ktime_t variable
- *
  * @kt:		addend
  * @nsec:	the scalar nsec value to add
  *
@@ -194,7 +190,6 @@ extern ktime_t ktime_add_ns(const ktime_
 
 /**
  * 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
@@ -207,7 +202,6 @@ static inline ktime_t timespec_to_ktime(
 
 /**
  * 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
@@ -220,7 +214,6 @@ static inline ktime_t timeval_to_ktime(c
 
 /**
  * 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
@@ -233,7 +226,6 @@ static inline struct timespec ktime_to_t
 
 /**
  * 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
--- linux-2617-pv.orig/include/linux/hrtimer.h
+++ linux-2617-pv/include/linux/hrtimer.h
@@ -40,7 +40,6 @@ struct hrtimer_base;
 
 /**
  * struct hrtimer - the basic hrtimer structure
- *
  * @node:	red black tree node for time ordered insertion
  * @expires:	the absolute expiry time in the hrtimers internal
  *		representation. The time is related to the clock on
@@ -59,7 +58,6 @@ struct hrtimer {
 
 /**
  * struct hrtimer_sleeper - simple sleeper structure
- *
  * @timer:	embedded timer structure
  * @task:	task to wake up
  *
@@ -72,7 +70,6 @@ struct hrtimer_sleeper {
 
 /**
  * struct hrtimer_base - the timer base for a specific clock
- *
  * @index:		clock type index for per_cpu support when moving a timer
  *			to a base on another cpu.
  * @lock:		lock protecting the base and associated timers
--- linux-2617-pv.orig/kernel/hrtimer.c
+++ linux-2617-pv/kernel/hrtimer.c
@@ -98,7 +98,6 @@ static DEFINE_PER_CPU(struct hrtimer_bas
 
 /**
  * ktime_get_ts - get the monotonic clock in timespec format
- *
  * @ts:		pointer to timespec variable
  *
  * The function calculates the monotonic clock from the realtime
@@ -238,7 +237,6 @@ lock_hrtimer_base(const struct hrtimer *
 # ifndef CONFIG_KTIME_SCALAR
 /**
  * ktime_add_ns - Add a scalar nanoseconds value to a ktime_t variable
- *
  * @kt:		addend
  * @nsec:	the scalar nsec value to add
  *
@@ -299,7 +297,6 @@ void unlock_hrtimer_base(const struct hr
 
 /**
  * hrtimer_forward - forward the timer expiry
- *
  * @timer:	hrtimer to forward
  * @now:	forward past this time
  * @interval:	the interval to forward
@@ -411,7 +408,6 @@ remove_hrtimer(struct hrtimer *timer, st
 
 /**
  * hrtimer_start - (re)start an relative timer on the current CPU
- *
  * @timer:	the timer to be added
  * @tim:	expiry time
  * @mode:	expiry mode: absolute (HRTIMER_ABS) or relative (HRTIMER_REL)
@@ -460,14 +456,13 @@ EXPORT_SYMBOL_GPL(hrtimer_start);
 
 /**
  * hrtimer_try_to_cancel - try to deactivate a timer
- *
  * @timer:	hrtimer to stop
  *
  * Returns:
  *  0 when the timer was not active
  *  1 when the timer was active
  * -1 when the timer is currently excuting the callback function and
- *    can not be stopped
+ *    cannot be stopped
  */
 int hrtimer_try_to_cancel(struct hrtimer *timer)
 {
@@ -489,7 +484,6 @@ 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:
@@ -510,7 +504,6 @@ EXPORT_SYMBOL_GPL(hrtimer_cancel);
 
 /**
  * hrtimer_get_remaining - get remaining time for the timer
- *
  * @timer:	the timer to read
  */
 ktime_t hrtimer_get_remaining(const struct hrtimer *timer)
@@ -564,7 +557,6 @@ ktime_t hrtimer_get_next_event(void)
 
 /**
  * hrtimer_init - initialize a timer to the given clock
- *
  * @timer:	the timer to be initialized
  * @clock_id:	the clock to be used
  * @mode:	timer mode abs/rel
@@ -588,7 +580,6 @@ EXPORT_SYMBOL_GPL(hrtimer_init);
 
 /**
  * hrtimer_get_res - get the timer resolution for a clock
- *
  * @which_clock: which clock to query
  * @tp:		 pointer to timespec variable to store the resolution
  *


---

Re: [PATCH] ktime/hrtimer: fix kernel-doc comments

[Thomas Gleixner]

Randy,

On Mon, 2006-06-19 at 13:09 -0700, Randy.Dunlap wrote:
> From: Randy Dunlap <rdunlap@xenotime.net>
> 
> Fix kernel-doc formatting in ktime.h and hrtimer.[ch] files.
> 
> Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
> ---
>  include/linux/hrtimer.h |    3 ---
>  include/linux/ktime.h   |    8 --------
>  kernel/hrtimer.c        |   11 +----------
>  3 files changed, 1 insertion(+), 21 deletions(-)
> 
> --- linux-2617-pv.orig/include/linux/ktime.h
> +++ linux-2617-pv/include/linux/ktime.h
> @@ -66,7 +66,6 @@ typedef union {
>  
>  /**
>   * ktime_set - Set a ktime_t variable from a seconds/nanoseconds value
> - *
>   * @secs:	seconds to set
>   * @nsecs:	nanoseconds to set
>   *
<.....>

Is there any real reason for doing this, expect for removing the blank
comment lines ? 

My personal preference is to keep that line, as it makes it easier to
read. But as always: de gustibus non est disputandum :)

	tglx

Re: [PATCH] ktime/hrtimer: fix kernel-doc comments

[Randy.Dunlap]

On Mon, 19 Jun 2006 23:00:22 +0200 Thomas Gleixner wrote:

> Randy,
> 
> On Mon, 2006-06-19 at 13:09 -0700, Randy.Dunlap wrote:
> > From: Randy Dunlap <rdunlap@xenotime.net>
> > 
> > Fix kernel-doc formatting in ktime.h and hrtimer.[ch] files.
> > 
> > Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
> > ---
> >  include/linux/hrtimer.h |    3 ---
> >  include/linux/ktime.h   |    8 --------
> >  kernel/hrtimer.c        |   11 +----------
> >  3 files changed, 1 insertion(+), 21 deletions(-)
> > 
> > --- linux-2617-pv.orig/include/linux/ktime.h
> > +++ linux-2617-pv/include/linux/ktime.h
> > @@ -66,7 +66,6 @@ typedef union {
> >  
> >  /**
> >   * ktime_set - Set a ktime_t variable from a seconds/nanoseconds value
> > - *
> >   * @secs:	seconds to set
> >   * @nsecs:	nanoseconds to set
> >   *
> <.....>
> 
> Is there any real reason for doing this, expect for removing the blank
> comment lines ? 

Hm, have you looked at the kernel-doc output of those functions?

With the blank line, the function Description section (if there
is one) is duplicated.  If there is not a Description section
in the source file, then there is a (false) header generated
for it but nothing below it.

> My personal preference is to keep that line, as it makes it easier to
> read. But as always: de gustibus non est disputandum :)

Feel free to send patches for scripts/kernel-doc instead.  :)

---
~Randy

Re: [PATCH] ktime/hrtimer: fix kernel-doc comments

[Thomas Gleixner]

On Mon, 2006-06-19 at 14:11 -0700, Randy.Dunlap wrote:
> > My personal preference is to keep that line, as it makes it easier to
> > read. But as always: de gustibus non est disputandum :)
> 
> Feel free to send patches for scripts/kernel-doc instead.  :)

Yeah, Russell King pointed me to the nano-howto 2 minutes ago. Not
reading docs is always backfiring at some point. :(

Seriously, is it hard to fix ? I'm not good with perl, so its likely
that I would make more mess than fixups.

	tglx

Re: [PATCH] ktime/hrtimer: fix kernel-doc comments

[Randy.Dunlap]

On Mon, 19 Jun 2006 23:15:33 +0200 Thomas Gleixner wrote:

> On Mon, 2006-06-19 at 14:11 -0700, Randy.Dunlap wrote:
> > > My personal preference is to keep that line, as it makes it easier to
> > > read. But as always: de gustibus non est disputandum :)
> > 
> > Feel free to send patches for scripts/kernel-doc instead.  :)
> 
> Yeah, Russell King pointed me to the nano-howto 2 minutes ago. Not
> reading docs is always backfiring at some point. :(
> 
> Seriously, is it hard to fix ? I'm not good with perl, so its likely
> that I would make more mess than fixups.

I don't know for sure.  I have looked at it a bit and
it's messy code IMHO.  Might be easier/better just to rewrite
the function (comment) header parsing.

Andrew also wants the short function description to be able to be
more than one line.  That could/should be incorporated at the same time.

OTOH, it's a defined doc. language and these files contain errors...

---
~Randy

PS: finally fixed Ingo's email address.

Re: [PATCH] ktime/hrtimer: fix kernel-doc comments

[Thomas Gleixner]

On Mon, 2006-06-19 at 14:20 -0700, Randy.Dunlap wrote:
> > Seriously, is it hard to fix ? I'm not good with perl, so its likely
> > that I would make more mess than fixups.
> 
> I don't know for sure.  I have looked at it a bit and
> it's messy code IMHO.  Might be easier/better just to rewrite
> the function (comment) header parsing.

I would do that, but I have no idea how to mix python into perl :)

> Andrew also wants the short function description to be able to be
> more than one line.  That could/should be incorporated at the same time.

That would be a really nice feature.

> OTOH, it's a defined doc. language and these files contain errors...

No objections, but it would be cool if some perl experts would remove
those restrictions before the patches finally hit mainline.

	tglx

Re: [PATCH] ktime/hrtimer: fix kernel-doc comments

[Randy.Dunlap]

On Mon, 19 Jun 2006 23:30:57 +0200 Thomas Gleixner wrote:

> On Mon, 2006-06-19 at 14:20 -0700, Randy.Dunlap wrote:
> > > Seriously, is it hard to fix ? I'm not good with perl, so its likely
> > > that I would make more mess than fixups.
> > 
> > I don't know for sure.  I have looked at it a bit and
> > it's messy code IMHO.  Might be easier/better just to rewrite
> > the function (comment) header parsing.
> 
> I would do that, but I have no idea how to mix python into perl :)

so rewrite scripts/kernel-doc in python.  ;)

> > Andrew also wants the short function description to be able to be
> > more than one line.  That could/should be incorporated at the same time.
> 
> That would be a really nice feature.

It's just a convenience factor.  There is another way to have a
multi-line function description.

> > OTOH, it's a defined doc. language and these files contain errors...
> 
> No objections, but it would be cool if some perl experts would remove
> those restrictions before the patches finally hit mainline.

I plan to work on it, but it's not super high priority.
Someone else can do the same...


This is just one example of many files that have similar kernel-doc
problems.  I wasn't picking on your files.  :)

---
~Randy

Re: [PATCH] ktime/hrtimer: fix kernel-doc comments

[Thomas Gleixner]

On Mon, 2006-06-19 at 14:41 -0700, Randy.Dunlap wrote:

> This is just one example of many files that have similar kernel-doc
> problems.  I wasn't picking on your files.  :)

I did not take it personal. I know that I missed to read the docs - as
always. I was just expressing my surprise about something I thought it
would be naturaly that way

	tglx