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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:   Mon, 15 May 2017 09:03:48 +0200
From:   Peter Zijlstra <peterz@...radead.org>
To:     Darren Hart <dvhart@...radead.org>
Cc:     Mauro Carvalho Chehab <mchehab@...pensource.com>,
        linux-kernel@...r.kernel.org,
        Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Mauro Carvalho Chehab <mchehab@...radead.org>,
        Ingo Molnar <mingo@...hat.com>,
        Thomas Gleixner <tglx@...utronix.de>
Subject: Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to
 generate ReST

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().
  */