From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S933103AbdEOK1i (ORCPT ); Mon, 15 May 2017 06:27:38 -0400 Received: from mga03.intel.com ([134.134.136.65]:30378 "EHLO mga03.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S932693AbdEOK1g (ORCPT ); Mon, 15 May 2017 06:27:36 -0400 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.38,344,1491289200"; d="scan'208";a="856892115" From: Jani Nikula To: Peter Zijlstra , Mauro Carvalho Chehab 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 In-Reply-To: <20170515093312.eaymomgkcetvpofc@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> Date: Mon, 15 May 2017 13:29:58 +0300 Message-ID: <874lwmmmzd.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: > 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. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center