From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752632AbdEMJmP (ORCPT ); Sat, 13 May 2017 05:42:15 -0400 Received: from ec2-52-27-115-49.us-west-2.compute.amazonaws.com ([52.27.115.49]:50939 "EHLO osg.samsung.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1752474AbdEMJmN (ORCPT ); Sat, 13 May 2017 05:42:13 -0400 Date: Sat, 13 May 2017 06:42:05 -0300 From: Mauro Carvalho Chehab To: Darren Hart Cc: Peter Zijlstra , 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: <20170513064205.03770eed@vento.lan> In-Reply-To: <20170512221917.GD17235@fury> References: <20170512164122.GA17235@fury> <20170512185150.5b48c5f6@vento.lan> <20170512221109.r6yuazrjpikrkg6d@hirez.programming.kicks-ass.net> <20170512221917.GD17235@fury> 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 Fri, 12 May 2017 15:19:17 -0700 Darren Hart escreveu: > 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.. Very few kerneldoc markups need changes due to ReST introduction, and usually is just whitespace/blank lines adjustment. Ok, someone could try to improve the script to make it smarter[1], but, on my experiences addressing it, usually doing the required changes make it visually better on both C file and on PDF/LaTeX/HTML outputs. [1] probably rewriting the entire script to work more like a lexical interpreter than a bunch of rejex expressions. > 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. IMHO, the best thing with kerneldoc is that it helps to keep the documentation updated, as it warns when someone change the function arguments without updating the comments. Thanks, Mauro