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]

Message-ID: <20170515093312.eaymomgkcetvpofc@hirez.programming.kicks-ass.net>
Date:   Mon, 15 May 2017 11:33:12 +0200
From:   Peter Zijlstra <peterz@...radead.org>
To:     Mauro Carvalho Chehab <mchehab@...pensource.com>
Cc:     Darren Hart <dvhart@...radead.org>, 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 Mon, May 15, 2017 at 06:00:46AM -0300, Mauro Carvalho Chehab wrote:

> > 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().
> >   */
> 
> What caused problems with the orignal markup is that Sphinx is
> highly oriented by indentation: different indentation levels on
> it cause troubles. A minimal change for it to be parsed would as 
> expected would be to remove the extra spaces that caused Sphinx
> to misinterpret the paragraph, e. g.:
> 
>  * ( The CONFIG_DEBUG_MUTEXES .config option turns on debugging
>  * checks that will enforce the restrictions and will also do
>  * deadlock debugging. )

That's ugly and doesn't read right either. Also C isn't whitespace
sensitive, so I don't feel we should add such brain damaged constraints
to our comments.

> But, if the intention of that spaces were to highlight the content
> inside the parenthesis (with is what I assumed), then the
> .. note markup will do the job. 

The intention is to aid readability. Making comments worse so that some
retarded script can generate better html or whatnot is just that,
retarded.

Code matters, generated documentation not so much. I'll take a comment
that reads well over one that generates pretty html any day.

> That's said, I guess it shouldn't be hard to add something at 
> kernel-doc script to convert some specially-crafted tag (like "Note:")
> to avoid having ReST notation for this specific case, e. g.:
> 
>  * Note:
>  *
>  * The CONFIG_DEBUG_MUTEXES .config option turns on debugging
>  * checks that will enforce the restrictions and will also do
>  * deadlock debugging.
> 
> Yet, IMHO, we should take some care to avoid adding much
> translations to it, as, otherwise, we'll end by having two
> markup languages instead of just one.

I'm all for _no_ markup language.