From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1758219AbdEOMGI (ORCPT ); Mon, 15 May 2017 08:06:08 -0400 Received: from mga02.intel.com ([134.134.136.20]:52357 "EHLO mga02.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752921AbdEOMGE (ORCPT ); Mon, 15 May 2017 08:06:04 -0400 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.38,344,1491289200"; d="scan'208";a="856916825" From: Jani Nikula To: Peter Zijlstra Cc: Mauro Carvalho Chehab , 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 In-Reply-To: <20170515114919.bepernrqonybkmmh@hirez.programming.kicks-ass.net> Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo 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> <20170515060046.7ba700c7@vento.lan> <20170515093312.eaymomgkcetvpofc@hirez.programming.kicks-ass.net> <874lwmmmzd.fsf@intel.com> <20170515114919.bepernrqonybkmmh@hirez.programming.kicks-ass.net> Date: Mon, 15 May 2017 15:05:49 +0300 Message-ID: <87tw4me34y.fsf@intel.com> MIME-Version: 1.0 Content-Type: text/plain Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Mon, 15 May 2017, Peter Zijlstra wrote: > On Mon, May 15, 2017 at 01:29:58PM +0300, Jani Nikula wrote: >> On Mon, 15 May 2017, Peter Zijlstra wrote: >> > 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. >> >> The deal is that if you start your comments with "/**" they'll be >> processed with the retarded script to produce pretty html. >> >> For the most part the comments that generate pretty html also read well, >> and we don't expect or want anyone to go overboard with markup. I don't >> think it's unreasonable to make small concessions to improve generated >> documentation for people who care about it even if you don't. > > No. Such a concession has pure negative value. It opens the door to more > patches converting this or that comment to be prettier or whatnot. And > before you know it there's a Markus like idiot spamming you with dozens > of crap patches to prettify the generated crud. > > Not to mention that this would mean having to learn this rest crud in > order to write these comments. > > All things I'm not prepared to do. > > I'm all for useful comments, but I see no value _at_all_ in this > generated nonsense. The only reason I sometimes use the docbook comment > style is because its fairly uniform and the build bot gets you a warning > when your function signature no longer matches with the comment. But > if you make this painful I'll simply stop using them. I see plenty of value in the generated documentation, but I see zero return on investment in spending any time trying to convince you about any of it. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center