Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST

[Peter Zijlstra]

On Fri, May 12, 2017 at 03:19:17PM -0700, Darren Hart wrote:
> On Sat, May 13, 2017 at 12:11:09AM +0200, Peter Zijlstra wrote:

> > And I really _really_ hate to see that rest crap spread here. Can't we
> > just delete all that nonsense and go back to 80 column 7bit ASCII ?
> > 
> 
> Depending on the source this could be a genuine appeal or satire.... :-D

A bit of both of course ;-)

> In this case, I don't think the ReST changes (with -) make the comment block any
> less readable in the C files.
> 
> > It is an incentive not to use kerneldoc..
> > 
> 
> I like the kerneldoc if for no other reason that it helps keeps formatting
> consistent. I would object if I started seeing XML or some other horrible
> formatting style showing up in the code, but this honestly seems like a fairly
> minimal imposition... but that's me.

Well, I don't mind the '-' thing before return values too much, but the
below chunk is just pure drivel. It makes a perfectly good comment
worse.

--- a/kernel/locking/mutex.c
+++ b/kernel/locking/mutex.c
@@ -227,9 +227,11 @@ static void __sched __mutex_lock_slowpath(struct mutex *lock);
  * (or statically defined) before it can be locked. memset()-ing
  * the mutex to 0 is not allowed.
  *
- * ( The CONFIG_DEBUG_MUTEXES .config option turns on debugging
+ * .. note::
+ *
+ *   The CONFIG_DEBUG_MUTEXES .config option turns on debugging
  *   checks that will enforce the restrictions and will also do
- *   deadlock debugging. )
+ *   deadlock debugging.
  *
  * This function is similar to (but not equivalent to) down().
  */