From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1758584AbdELWTW (ORCPT ); Fri, 12 May 2017 18:19:22 -0400 Received: from bombadil.infradead.org ([65.50.211.133]:35215 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752008AbdELWTT (ORCPT ); Fri, 12 May 2017 18:19:19 -0400 Date: Fri, 12 May 2017 15:19:17 -0700 From: Darren Hart To: Peter Zijlstra Cc: Mauro Carvalho Chehab , 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: <20170512221917.GD17235@fury> References: <20170512164122.GA17235@fury> <20170512185150.5b48c5f6@vento.lan> <20170512221109.r6yuazrjpikrkg6d@hirez.programming.kicks-ass.net> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20170512221109.r6yuazrjpikrkg6d@hirez.programming.kicks-ass.net> User-Agent: Mutt/1.8.0 (2017-02-23) Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Sat, May 13, 2017 at 12:11:09AM +0200, Peter Zijlstra wrote: > On Fri, May 12, 2017 at 06:51:50PM -0300, Mauro Carvalho Chehab wrote: > > > * Return: > > > * * 0 - ready to wait > > > * * 1 - acquired the lock > > > * * <0 - error > > > > > > I'm fine with either though, just curious if this would be an improvement, or if > > > we have an established policy (which I didn't find in the docs on docs...). > > > > I prefer myself to use "-". IMHO, a dash is visually less polluted > > than an asterisk, when reading text files, but I guess this is a > > matter of taste. > > Not to mention it just reads very awkward in a comment. I don't much > care about it in any other context. Agreed, the - is better (and equally functional - so yay). > > 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 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. -- Darren Hart VMware Open Source Technology Center