[PATCH] include/linux/mutex.h: unclear reference to convention

[PATCH] include/linux/mutex.h: unclear reference to convention

[Matti Linnanvuori]

Randy Dunlap <randy.dunlap@oracle.com>:
> Another convention is that we put kernel-doc with the implementation
> (i.e., in .c files) when possible, not with the function prototype.
> Of course, for inline functions or macros in header files, that's
> where the kernel-doc has to live.
>
> so we don't need this patch.

 You should not expect that every reader of the kernel files is aware of 
that convention. I was not and therefore I sought referenced files for 
some time.





      Machen Sie Yahoo! zu Ihrer Startseite. Los geht's: 
http://de.yahoo.com/set

Re: [PATCH] include/linux/mutex.h: unclear reference to convention

[Randy Dunlap]

Matti Linnanvuori wrote:
> Randy Dunlap <randy.dunlap@oracle.com>:
>> Another convention is that we put kernel-doc with the implementation
>> (i.e., in .c files) when possible, not with the function prototype.
>> Of course, for inline functions or macros in header files, that's
>> where the kernel-doc has to live.
>>
>> so we don't need this patch.
> 
>  You should not expect that every reader of the kernel files is aware of 
> that convention. I was not and therefore I sought referenced files for 
> some time.

Sure, I agree with you.
Where should we put this information so that people will find it?

-- 
~Randy
Phaedrus says that Quality is about caring.

[PATCH] include/linux/mutex.h: unclear reference to convention

[Matti Linnanvuori]

If you want to maintain the convention of documenting the interface only in .c files, 
you should write the convention in so many places in .h files that no one could overlook it.
But I think the convention is bad and it would be better to document the interface also in
.h files where it is defined. The convention is bad because it requires people to jump to
other files to understand .h files.



      __________________________________  
Alles was der Gesundheit und Entspannung dient. BE A BETTER MEDIZINMANN! www.yahoo.de/clever

Re: [PATCH] include/linux/mutex.h: unclear reference to convention

[Randy Dunlap]

On Tue, 25 Sep 2007 01:11:05 -0700 (PDT) Matti Linnanvuori wrote:

> If you want to maintain the convention of documenting the interface only in .c files, 
> you should write the convention in so many places in .h files that no one could overlook it.
> But I think the convention is bad and it would be better to document the interface also in
> .h files where it is defined. The convention is bad because it requires people to jump to
> other files to understand .h files.

Then we would have comments in multiple places and they would
undoubtedly get out of sync.  When that happens, which one do
you use?  Bad.

I'll find some place to document this convention anyway.  Maybe
it will help.

---
~Randy
Phaedrus says that Quality is about caring.

[PATCH] include/linux/mutex.h: unclear reference to convention

[Matti Linnanvuori]

From: Matti Linnanvuori <mattilinnanvuori@yahoo.com>

Reference to two different conventions is unnecessarily unclear unless you know them already and requires seeking and reading another file for understanding.

Signed-off-by: Matti Linnanvuori <mattilinnanvuori@yahoo.com>
---

--- linux-2.6.23-rc7/include/linux/mutex.h    2007-09-22 11:09:42.223763000 +0300
+++ linux-2.6.23/include/linux/mutex.h    2007-09-22 11:11:19.416761000 +0300
@@ -132,9 +132,19 @@ extern int __must_check mutex_lock_inter
 # define mutex_lock_interruptible_nested(lock, subclass) mutex_lock_interruptible(lock)
 #endif
 
-/*
- * NOTE: mutex_trylock() follows the spin_trylock() convention,
- *       not the down_trylock() convention!
+/***
+ * mutex_trylock - try acquire the mutex, without waiting
+ * @lock: the mutex to be acquired
+ *
+ * Try to acquire the mutex atomically. Returns 1 if the mutex
+ * has been acquired successfully, and 0 on contention.
+ *
+ * NOTE: this function follows the spin_trylock() convention, so
+ * it is negated to the down_trylock() return values! Be careful
+ * about this when converting semaphore users to mutexes.
+ *
+ * This function must not be used in interrupt context. The
+ * mutex must be released by the same task that acquired it.
  */
 extern int fastcall mutex_trylock(struct mutex *lock);
 extern void fastcall mutex_unlock(struct mutex *lock);





      ________ 
Yahoo! Clever: Stellen Sie Fragen und finden Sie Antworten. Teilen Sie Ihr Wissen. www.yahoo.de/clever

Re: [PATCH] include/linux/mutex.h: unclear reference to convention

[Randy Dunlap]

On Sat, 22 Sep 2007 01:41:17 -0700 (PDT) Matti Linnanvuori wrote:

> From: Matti Linnanvuori <mattilinnanvuori@yahoo.com>
> 
> Reference to two different conventions is unnecessarily unclear unless you know them already and requires seeking and reading another file for understanding.


Could you hit the Return/Enter key about every 70-72 characters or so,
to break up those long lines?
Thanks.

> Signed-off-by: Matti Linnanvuori <mattilinnanvuori@yahoo.com>
> ---
> 
> --- linux-2.6.23-rc7/include/linux/mutex.h    2007-09-22 11:09:42.223763000 +0300
> +++ linux-2.6.23/include/linux/mutex.h    2007-09-22 11:11:19.416761000 +0300
> @@ -132,9 +132,19 @@ extern int __must_check mutex_lock_inter
>  # define mutex_lock_interruptible_nested(lock, subclass) mutex_lock_interruptible(lock)
>  #endif
>  
> -/*
> - * NOTE: mutex_trylock() follows the spin_trylock() convention,
> - *       not the down_trylock() convention!

Someone was trying to be helpful in include/linux/mutex.h.
The real doc for the function is in kernel/mutex.c (and pasted
below).

Another convention is that we put kernel-doc with the implementation
(i.e., in .c files) when possible, not with the function prototype.
Of course, for inline functions or macros in header files, that's
where the kernel-doc has to live.

so we don't need this patch.


> +/***
> + * mutex_trylock - try acquire the mutex, without waiting
> + * @lock: the mutex to be acquired
> + *
> + * Try to acquire the mutex atomically. Returns 1 if the mutex
> + * has been acquired successfully, and 0 on contention.
> + *
> + * NOTE: this function follows the spin_trylock() convention, so
> + * it is negated to the down_trylock() return values! Be careful
> + * about this when converting semaphore users to mutexes.
> + *
> + * This function must not be used in interrupt context. The
> + * mutex must be released by the same task that acquired it.
>   */
>  extern int fastcall mutex_trylock(struct mutex *lock);
>  extern void fastcall mutex_unlock(struct mutex *lock);


---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***