From: Jani Nikula <jani.nikula@linux.intel.com>
To: Peter Zijlstra <peterz@infradead.org>,
Mauro Carvalho Chehab <mchehab@s-opensource.com>
Cc: Darren Hart <dvhart@infradead.org>,
linux-kernel@vger.kernel.org,
Linux Doc Mailing List <linux-doc@vger.kernel.org>,
Mauro Carvalho Chehab <mchehab@infradead.org>,
Ingo Molnar <mingo@redhat.com>,
Thomas Gleixner <tglx@linutronix.de>
Subject: Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST
Date: Mon, 15 May 2017 13:29:58 +0300 [thread overview]
Message-ID: <874lwmmmzd.fsf@intel.com> (raw)
In-Reply-To: <20170515093312.eaymomgkcetvpofc@hirez.programming.kicks-ass.net>
On Mon, 15 May 2017, Peter Zijlstra <peterz@infradead.org> 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
next prev parent reply other threads:[~2017-05-15 10:27 UTC|newest]
Thread overview: 67+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <cover.1494596071.git.mchehab@s-opensource.com>
2017-05-12 13:59 ` [PATCH 01/36] docs-rst: convert kernel-hacking to ReST Mauro Carvalho Chehab
2017-05-12 16:35 ` Markus Heiser
2017-05-13 10:03 ` Mauro Carvalho Chehab
2017-05-15 16:50 ` Jonathan Corbet
2017-05-12 13:59 ` [PATCH 02/36] kernel-hacking: update document Mauro Carvalho Chehab
2017-05-12 13:59 ` [PATCH 03/36] docs-rst: convert kernel-locking to ReST Mauro Carvalho Chehab
2017-05-12 16:49 ` Markus Heiser
2017-05-12 16:57 ` Markus Heiser
2017-05-13 9:25 ` Mauro Carvalho Chehab
2017-05-12 13:59 ` [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST Mauro Carvalho Chehab
2017-05-12 16:41 ` Darren Hart
2017-05-12 21:51 ` Mauro Carvalho Chehab
2017-05-12 22:08 ` Darren Hart
2017-05-12 22:11 ` Peter Zijlstra
2017-05-12 22:19 ` Darren Hart
2017-05-13 9:42 ` Mauro Carvalho Chehab
2017-05-15 7:03 ` Peter Zijlstra
2017-05-15 9:00 ` Mauro Carvalho Chehab
2017-05-15 9:33 ` Peter Zijlstra
2017-05-15 10:29 ` Jani Nikula [this message]
2017-05-15 11:49 ` Peter Zijlstra
2017-05-15 12:05 ` Jani Nikula
2017-05-15 16:40 ` Darren Hart
2017-05-16 10:13 ` Mauro Carvalho Chehab
2017-05-15 17:22 ` Mauro Carvalho Chehab
2017-05-16 11:16 ` Peter Zijlstra
2017-05-16 11:41 ` Mauro Carvalho Chehab
2017-05-12 13:59 ` [PATCH 05/36] locking.rst: reformat locking table Mauro Carvalho Chehab
2017-05-12 13:59 ` [PATCH 06/36] locking.rst: add captions to two tables Mauro Carvalho Chehab
2017-05-12 13:59 ` [PATCH 07/36] locking.rst: Update some ReST markups Mauro Carvalho Chehab
2017-05-12 13:59 ` [PATCH 08/36] docs-rst: convert kgdb DocBook to ReST Mauro Carvalho Chehab
2017-05-12 13:59 ` [PATCH 09/36] kgdb.rst: Adjust ReST markups Mauro Carvalho Chehab
2017-05-12 13:59 ` [PATCH 10/36] conf.py: define a color for important markup on PDF output Mauro Carvalho Chehab
2017-05-12 13:59 ` [PATCH 11/36] docs-rst: conf.py: sort LaTeX documents in alphabetical order Mauro Carvalho Chehab
2017-05-12 13:59 ` [PATCH 12/36] docs-rst: conf.py: remove kernel-documentation from LaTeX Mauro Carvalho Chehab
2017-05-12 13:59 ` [PATCH 13/36] docs-rst: add crypto API book to pdf output Mauro Carvalho Chehab
2017-05-12 13:59 ` [PATCH 14/36] docs-rst: add dev-tools " Mauro Carvalho Chehab
2017-05-12 13:59 ` [PATCH 15/36] docs-rst: add sound " Mauro Carvalho Chehab
2017-05-12 13:59 ` [PATCH 16/36] docs-rst: add userspace API " Mauro Carvalho Chehab
2017-05-12 14:00 ` [PATCH 17/36] docs-rst: convert filesystems book to ReST Mauro Carvalho Chehab
2017-05-12 14:00 ` [PATCH 18/36] docs-rst: filesystems: use c domain references where needed Mauro Carvalho Chehab
2017-05-12 14:00 ` [PATCH 19/36] fs: jbd2: make jbd2_journal_start() kernel-doc parseable Mauro Carvalho Chehab
2017-05-15 13:06 ` Jan Kara
2017-05-12 14:00 ` [PATCH 20/36] docs-rst: don't ignore internal functions for jbd2 docs Mauro Carvalho Chehab
2017-05-12 14:00 ` [PATCH 21/36] fs: locks: Fix some troubles at kernel-doc comments Mauro Carvalho Chehab
2017-05-12 14:02 ` Jeff Layton
2017-05-13 9:14 ` Mauro Carvalho Chehab
2017-05-15 14:51 ` J. Bruce Fields
2017-05-12 14:00 ` [PATCH 22/36] fs: add a blank lines on some " Mauro Carvalho Chehab
2017-05-12 14:00 ` [PATCH 23/36] fs: eventfd: fix identation on kernel-doc Mauro Carvalho Chehab
2017-05-12 14:00 ` [PATCH 24/36] fs: jbd2: escape a string with special chars on a kernel-doc Mauro Carvalho Chehab
2017-05-15 13:05 ` Jan Kara
2017-05-12 14:00 ` [PATCH 25/36] docs-rst: convert libata book to ReST Mauro Carvalho Chehab
2017-05-12 14:00 ` [PATCH 26/36] libata.rst: add c function and struct cross-references Mauro Carvalho Chehab
2017-05-13 6:57 ` kbuild test robot
2017-05-12 14:00 ` [PATCH 27/36] libata: fix identation on a kernel-doc markup Mauro Carvalho Chehab
2017-05-12 14:00 ` [PATCH 28/36] docs-rst: convert s390-drivers DocBook to ReST Mauro Carvalho Chehab
2017-05-15 8:09 ` Cornelia Huck
2017-05-16 9:19 ` Mauro Carvalho Chehab
2017-05-12 14:00 ` [PATCH 29/36] docs-rst: convert networking book " Mauro Carvalho Chehab
2017-05-12 14:00 ` [PATCH 30/36] net: skbuff.h: properly escape a macro name on kernel-doc Mauro Carvalho Chehab
2017-05-12 14:00 ` [PATCH 31/36] net: fix some identation issues at kernel-doc markups Mauro Carvalho Chehab
2017-05-12 14:00 ` [PATCH 32/36] docs-rst: convert z8530book DocBook to ReST Mauro Carvalho Chehab
2017-05-12 14:00 ` [PATCH 33/36] docs-rst: convert scsi " Mauro Carvalho Chehab
2017-05-12 14:00 ` [PATCH 34/36] scsi: fix some kernel-doc markups Mauro Carvalho Chehab
2017-05-12 14:00 ` [PATCH 35/36] docs-rst: convert w1 book to ReST Mauro Carvalho Chehab
2017-05-12 14:00 ` [PATCH 36/36] docs-rst: convert rapidio " Mauro Carvalho Chehab
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=874lwmmmzd.fsf@intel.com \
--to=jani.nikula@linux.intel.com \
--cc=dvhart@infradead.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=mchehab@infradead.org \
--cc=mchehab@s-opensource.com \
--cc=mingo@redhat.com \
--cc=peterz@infradead.org \
--cc=tglx@linutronix.de \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox