mirror of https://lore.kernel.org/lkml/
 help / color / mirror / Atom feed
From: James Bottomley <James.Bottomley@HansenPartnership.com>
To: Ingo Molnar <mingo@elte.hu>
Cc: Andy Whitcroft <apw@canonical.com>,
	Alan Stern <stern@rowland.harvard.edu>,
	Peter Zijlstra <peterz@infradead.org>,
	Andrew Morton <akpm@linux-foundation.org>,
	Kernel development list <linux-kernel@vger.kernel.org>,
	Randy Dunlap <randy.dunlap@oracle.com>
Subject: Re: [PATCH] Add kerneldoc for flush_scheduled_work()
Date: Thu, 13 Aug 2009 09:37:59 -0500	[thread overview]
Message-ID: <1250174279.3901.21.camel@mulgrave.site> (raw)
In-Reply-To: <20090813072514.GF12143@elte.hu>

On Thu, 2009-08-13 at 09:25 +0200, Ingo Molnar wrote:
> * James Bottomley <James.Bottomley@HansenPartnership.com> wrote:
> 
> > On Wed, 2009-08-12 at 10:13 -0400, Alan Stern wrote:
> > > On Wed, 12 Aug 2009, Ingo Molnar wrote:
> > > 
> > > > > And here I was thinking kerneldoc doesn't actually work 
> > > > > like that, but perhaps Randy fixed it so the initial 
> > > > > description can line-wrap?
> > > 
> > > Yes, that's what I thought too.  If kerneldoc has been fixed 
> > > then the description line certainly should get wrapped.
> > 
> > I really don't think it needs to be fixed: it's a feature not a 
> > bug.  It requires people writing kernel doc actually to think of 
> > one line summaries.
> 
> As long as the argument is that it's good to have limitations just 
> because it has good effects as well (which the gist of your argument 
> seems to be), i disagree.

You're free to disagree

> That's a very basic argument of freedom. Just consider the Gestapo 
> which was also a 'feature' to keep criminals in check. Did you know 
> that there were record low levels of petty criminality both in nazi 
> Germany and during communism (and under just about any totalitarian 
> regime)? Still nobody in their right mind is arguing that just due 
> to that they are the right social model ...
> 
> I think this DocBook limitation needs to be fixed, because there are 
> legitimate cases where a function name got too long (for no fault of 
> its own, but for properties of the name-space it is operating in), 
> and we do not want a nanny state beat it into a single line.

But your argument is bogus.  We have tons of additional rules in Linux
coding and we have a variety of enforcement mechanisms from BUILD_BUG_ON
through to checkpatch.pl.  This really doesn't have anything to do with
"freedom".

There are really two questions here

     1. Is it a good rule that our oneline docbook function summaries
        should be, well, one line?
     2. Is the enforcement mechanism for this rule adequate?

I think 1. is reasonable.  I think 2. needs work because you don't see
the problem until make doc.

James



  parent reply	other threads:[~2009-08-13 14:38 UTC|newest]

Thread overview: 41+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2009-08-11 21:06 Alan Stern
2009-08-12  9:41 ` Ingo Molnar
2009-08-12 10:47   ` Peter Zijlstra
2009-08-12 10:51     ` Ingo Molnar
2009-08-12 14:13       ` Alan Stern
2009-08-12 14:17         ` Ingo Molnar
2009-08-12 15:56           ` [PATCH ver 2] " Alan Stern
2009-08-12 16:22         ` [PATCH] " James Bottomley
2009-08-13  7:25           ` Ingo Molnar
2009-08-13  8:47             ` Johannes Weiner
2009-08-13 10:03               ` Ingo Molnar
2009-08-13 14:37             ` James Bottomley [this message]
2009-08-12 14:01 ` James Bottomley
2009-08-12 14:54   ` Alan Stern
2009-08-12 15:00     ` James Bottomley
2009-08-12 15:44       ` Alan Stern
2009-08-12 15:58         ` James Bottomley
2009-08-12 16:23           ` Alan Stern
2009-08-12 17:02             ` James Bottomley
2009-08-12 17:25               ` Alan Stern
2009-08-12 17:36                 ` James Bottomley
2009-08-12 18:16                   ` Alan Stern
2009-08-12 18:27                     ` James Bottomley
2009-08-12 18:48                       ` Alan Stern
2009-08-12 20:28                         ` James Bottomley
2009-08-12 20:41                           ` Alan Stern
2009-08-12 18:14 Randy Dunlap
2009-08-13 12:06 Randy Dunlap
2009-08-13 14:51 ` Johannes Weiner
2009-08-13 15:04   ` James Bottomley
2009-08-13 16:20     ` Randy Dunlap
2009-08-13 18:08       ` Johannes Weiner
2009-08-14 18:23         ` Randy Dunlap
2009-08-18  9:04           ` Johannes Weiner
2009-08-19 22:23             ` Johannes Weiner
2009-08-19 23:21               ` Randy Dunlap
2009-08-19 23:27                 ` Randy Dunlap
2009-08-24 19:06                 ` Johannes Weiner
2009-08-24 19:27                   ` Randy Dunlap
2009-08-24 20:09                     ` Johannes Weiner
2009-08-24 20:25                       ` Randy Dunlap

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=1250174279.3901.21.camel@mulgrave.site \
    --to=james.bottomley@hansenpartnership.com \
    --cc=akpm@linux-foundation.org \
    --cc=apw@canonical.com \
    --cc=linux-kernel@vger.kernel.org \
    --cc=mingo@elte.hu \
    --cc=peterz@infradead.org \
    --cc=randy.dunlap@oracle.com \
    --cc=stern@rowland.harvard.edu \
    /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

all inboxes | Powered by JetHome®