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

[Jani Nikula]

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