Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1641580

Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST

Show all headers | View raw

On Mon, May 15, 2017 at 01:29:58PM +0300, Jani Nikula wrote:
> 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.

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.

Back to linux.kernel | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

[PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-12 16:10 +0200
  Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to  generate ReST Darren Hart <dvhart@infradead.org> - 2017-05-12 18:50 +0200
    Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to  generate ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-13 00:00 +0200
      Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to  generate ReST Darren Hart <dvhart@infradead.org> - 2017-05-13 00:20 +0200
        Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to  generate ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-13 11:50 +0200
        Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to  generate ReST Peter Zijlstra <peterz@infradead.org> - 2017-05-15 09:10 +0200
          Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to  generate ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-15 11:10 +0200
            Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to  generate ReST Peter Zijlstra <peterz@infradead.org> - 2017-05-15 11:40 +0200
              Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST Jani Nikula <jani.nikula@linux.intel.com> - 2017-05-15 12:30 +0200
                Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to  generate ReST Peter Zijlstra <peterz@infradead.org> - 2017-05-15 13:50 +0200
                Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST Jani Nikula <jani.nikula@linux.intel.com> - 2017-05-15 14:10 +0200
                Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to  generate ReST Darren Hart <dvhart@infradead.org> - 2017-05-15 18:50 +0200
                Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to  generate ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 12:20 +0200
                Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to  generate ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-15 19:30 +0200
                Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to  generate ReST Peter Zijlstra <peterz@infradead.org> - 2017-05-16 13:20 +0200
                Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to  generate ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 13:50 +0200
      Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to  generate ReST Darren Hart <dvhart@infradead.org> - 2017-05-13 00:20 +0200
      Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to  generate ReST Peter Zijlstra <peterz@infradead.org> - 2017-05-13 00:20 +0200

csiph-web