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
next prev 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®