From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S933609AbdEOJBH (ORCPT ); Mon, 15 May 2017 05:01:07 -0400 Received: from ec2-52-27-115-49.us-west-2.compute.amazonaws.com ([52.27.115.49]:54412 "EHLO osg.samsung.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S933563AbdEOJBE (ORCPT ); Mon, 15 May 2017 05:01:04 -0400 Date: Mon, 15 May 2017 06:00:46 -0300 From: Mauro Carvalho Chehab To: Peter Zijlstra Cc: Darren Hart , linux-kernel@vger.kernel.org, Linux Doc Mailing List , Mauro Carvalho Chehab , Ingo Molnar , Thomas Gleixner Subject: Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST Message-ID: <20170515060046.7ba700c7@vento.lan> In-Reply-To: <20170515070348.htsggm7rgggaqrpd@hirez.programming.kicks-ass.net> References: <20170512164122.GA17235@fury> <20170512185150.5b48c5f6@vento.lan> <20170512221109.r6yuazrjpikrkg6d@hirez.programming.kicks-ass.net> <20170512221917.GD17235@fury> <20170515070348.htsggm7rgggaqrpd@hirez.programming.kicks-ass.net> Organization: Samsung X-Mailer: Claws Mail 3.14.1 (GTK+ 2.24.31; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Em Mon, 15 May 2017 09:03:48 +0200 Peter Zijlstra escreveu: > 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(). > */ 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. ) 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. 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. Thanks, Mauro