[PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[Steven Cole]

Maybe the following should be unnecessary after all these years since
the ANSI C standard was introduced, but several files associated with
zlib were using the old-style function declaration.

So, here is a proposed addition to CodingStyle, just to make it clear.

Steven


--- bk-current/Documentation/CodingStyle	Fri May 30 09:20:33 2003
+++ linux/Documentation/CodingStyle	Fri May 30 13:16:30 2003
@@ -149,6 +149,21 @@
 and it gets confused.  You know you're brilliant, but maybe you'd like
 to understand what you did 2 weeks from now. 
 
+Function declarations should be new-style:
+
+int foo(long bar, long day, struct magic *xyzzy)
+or
+int foo(
+	long bar,
+	long day,
+	struct magic *xyzzy
+)
+
+Old-style function declarations are deprecated:
+
+int foo(bar, day, xyzzy)
+long bar, day;
+struct magic *xyzzy;
 
 		Chapter 5: Commenting
 

Re: [PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[Jörn Engel]

On Fri, 30 May 2003 13:57:13 -0600, Steven Cole wrote:
> 
> Maybe the following should be unnecessary after all these years since
> the ANSI C standard was introduced, but several files associated with
> zlib were using the old-style function declaration.
> 
> So, here is a proposed addition to CodingStyle, just to make it clear.

In the case of the zlib, just leave it as it is.  The less changes we
make, to easier it is to merge upstream changes into the kernel.

Jörn

-- 
You can't tell where a program is going to spend its time. Bottlenecks
occur in surprising places, so don't try to second guess and put in a
speed hack until you've proven that's where the bottleneck is.
-- Rob Pike

Re: [PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[Steven Cole]

On Fri, 2003-05-30 at 14:14, Jörn Engel wrote:
> On Fri, 30 May 2003 13:57:13 -0600, Steven Cole wrote:
> > 
> > Maybe the following should be unnecessary after all these years since
> > the ANSI C standard was introduced, but several files associated with
> > zlib were using the old-style function declaration.
> > 
> > So, here is a proposed addition to CodingStyle, just to make it clear.
> 
> In the case of the zlib, just leave it as it is.  The less changes we
> make, to easier it is to merge upstream changes into the kernel.
> 
> Jörn

Whoops, sorry.  Linus started the old-style to new-style conversion in
zlib_inflate a few days ago, and I've sent Linus several patches
finishing the job in zlib_deflate and elsewhere.  Some are already in
the tree.

Steven

Re: [PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[Jörn Engel]

On Fri, 30 May 2003 14:25:07 -0600, Steven Cole wrote:
> On Fri, 2003-05-30 at 14:14, Jörn Engel wrote:
> > On Fri, 30 May 2003 13:57:13 -0600, Steven Cole wrote:
> > > 
> > > Maybe the following should be unnecessary after all these years since
> > > the ANSI C standard was introduced, but several files associated with
> > > zlib were using the old-style function declaration.
> > 
> > In the case of the zlib, just leave it as it is.  The less changes we
> > make, to easier it is to merge upstream changes into the kernel.
> 
> Whoops, sorry.  Linus started the old-style to new-style conversion in
> zlib_inflate a few days ago, and I've sent Linus several patches
> finishing the job in zlib_deflate and elsewhere.  Some are already in
> the tree.

I would agree with that strategy, if the zlib wasn't actively
maintained anymore and we'd have to take over that part anyway.  But
as it is, this will create extra work with little bonus on our side,
except to set a better example maybe.

Linus, any insight to your reasons for this change?

Jörn

-- 
Rules of Optimization:
Rule 1: Don't do it.
Rule 2 (for experts only): Don't do it yet.
-- M.A. Jackson 

Re: [PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[Linus Torvalds]

On Fri, 30 May 2003, Jörn Engel wrote:
> 
> I would agree with that strategy, if the zlib wasn't actively
> maintained anymore and we'd have to take over that part anyway.  But
> as it is, this will create extra work with little bonus on our side,
> except to set a better example maybe.
> 
> Linus, any insight to your reasons for this change?

I personally consider K&R prototypes to be useless, and downright evil. 
Any project who still has them is either lazy or still living in the 80's, 
and in either case I don't see any reason not to clean up the kernel side.

Besides, I'm not aware of any reason to ever really sync with zlib on that
level (the kinds of syncs I do foresee would be security issues or similar
if some exploit is found, but that's unlikely to be a major sync).

We've historically done other surgery to the zlib sources to make them a
bit more readable at times (the zlib allocator was just doing ridiculous
things, the kernel version was changed to allocate small structures
directly on the stack and embed others statically).

		Linus

Re: [PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[Jörn Engel]

On Fri, 30 May 2003 13:48:12 -0700, Linus Torvalds wrote:
> 
> I personally consider K&R prototypes to be useless, and downright evil. 
> Any project who still has them is either lazy or still living in the 80's, 
> and in either case I don't see any reason not to clean up the kernel side.
> 
> Besides, I'm not aware of any reason to ever really sync with zlib on that
> level (the kinds of syncs I do foresee would be security issues or similar
> if some exploit is found, but that's unlikely to be a major sync).
> 
> We've historically done other surgery to the zlib sources to make them a
> bit more readable at times (the zlib allocator was just doing ridiculous
> things, the kernel version was changed to allocate small structures
> directly on the stack and embed others statically).

How about an all or nothing approach?  If you really want to get rid
of K&R, change indentation as well, rip out some of the rather
tasteless macros (ZEXPORT, ZEXPORTVA, ZEXTERN, FAR, ...) and so on.
The code is ugly, no doubt, but has the advantage of being close to
the upstream variant.  I would hate to have the combined problems of
ugly and forked code.

You do have a point with the sync size.  The diff between 1.1.3 and
1.1.4 is 90k, of which only some 5k are functional changes.  The rest
extends the copyright times, adds/changes documentation, etc.

Jörn

-- 
A defeated army first battles and then seeks victory.
-- Sun Tzu

Re: [PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[Linus Torvalds]

On Fri, 30 May 2003, Jörn Engel wrote:
> 
> How about an all or nothing approach?  If you really want to get rid
> of K&R, change indentation as well, rip out some of the rather
> tasteless macros (ZEXPORT, ZEXPORTVA, ZEXTERN, FAR, ...) and so on.

I'd love to, but I suspect we lack the motivation to do so, and there 
aren't any obvious upsides. Yes, the code is ugly, but it's also fairly 
stable so people seldom need to look at it.

The motivation for doing the ANSI-fication is just that there is now a 
sanity checker tool that will complain loudly about bad typing, and since 
I wrote it and I hate old-style K&R sources, it doesn't parse them. 

> You do have a point with the sync size.  The diff between 1.1.3 and
> 1.1.4 is 90k, of which only some 5k are functional changes.  The rest
> extends the copyright times, adds/changes documentation, etc.

I wouldn't mind syncing more, but one reason _against_ syncing the zlib 
sources have been the ugliness of them. Is there any reason for the 
K&R'ness any more, or the strange allocators?

		Linus

Re: [PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[Jörn Engel]

On Fri, 30 May 2003 14:38:07 -0700, Linus Torvalds wrote:
> On Fri, 30 May 2003, Jörn Engel wrote:
> > 
> > How about an all or nothing approach?  If you really want to get rid
> > of K&R, change indentation as well, rip out some of the rather
> > tasteless macros (ZEXPORT, ZEXPORTVA, ZEXTERN, FAR, ...) and so on.
> 
> I'd love to, but I suspect we lack the motivation to do so, and there 
> aren't any obvious upsides. Yes, the code is ugly, but it's also fairly 
> stable so people seldom need to look at it.

Well, since I'm currently working on the zlib anyway...

> The motivation for doing the ANSI-fication is just that there is now a 
> sanity checker tool that will complain loudly about bad typing, and since 
> I wrote it and I hate old-style K&R sources, it doesn't parse them. 

Sounds nice.  Did I miss it on lkml, or haven't you made it public
yet?

> I wouldn't mind syncing more, but one reason _against_ syncing the zlib 
> sources have been the ugliness of them. Is there any reason for the 
> K&R'ness any more, or the strange allocators?

The allocaters could be useful when lots of zlibs are fighting over
scarce memory, at least when operating in userspace.  K&R and
indentation seem to be personal style (inflate and deflate also have a
different style, when you look closely).  FAR, uInt and friends should
be portability wrappers, there was even a turboc bugfix in the code
before 1.1.4.

Who knows, the performance might even slightly improve after shaving
off some of the useless wrappers.

Jörn

-- 
Geld macht nicht glücklich.
Glück macht nicht satt.

Re: [PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[Davide Libenzi]

On Sat, 31 May 2003, [iso-8859-1] Jörn Engel wrote:

> On Fri, 30 May 2003 14:38:07 -0700, Linus Torvalds wrote:
> > On Fri, 30 May 2003, Jörn Engel wrote:
> > >
> > > How about an all or nothing approach?  If you really want to get rid
> > > of K&R, change indentation as well, rip out some of the rather
> > > tasteless macros (ZEXPORT, ZEXPORTVA, ZEXTERN, FAR, ...) and so on.
> >
> > I'd love to, but I suspect we lack the motivation to do so, and there
> > aren't any obvious upsides. Yes, the code is ugly, but it's also fairly
> > stable so people seldom need to look at it.
>
> Well, since I'm currently working on the zlib anyway...

Talking about the code, there are still a bunch of files that uses spaces
with tabsize=4. Shouldn't those be reformatted with real TABs ? An emacs
lisp (indent+tabify) might do it pretty fast ...



- Davide

Re: [PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[Alan Cox]

On Gwe, 2003-05-30 at 23:39, Davide Libenzi wrote:
> Talking about the code, there are still a bunch of files that uses spaces
> with tabsize=4. Shouldn't those be reformatted with real TABs ? An emacs
> lisp (indent+tabify) might do it pretty fast ...

indent -kr -i8 -bri0 -l255 

seems to do the job even faster. I did a pile of the scsi drivers when I
went over them. The big thing is not to mix indent with real changes.
Its always a temptation but its vital that there are no outstanding
changes and that a patch exists where you can test before and after
indent to verify that change didnt cause the problems

Re: [PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[Davide Libenzi]

On Fri, 30 May 2003, Alan Cox wrote:

> On Gwe, 2003-05-30 at 23:39, Davide Libenzi wrote:
> > Talking about the code, there are still a bunch of files that uses spaces
> > with tabsize=4. Shouldn't those be reformatted with real TABs ? An emacs
> > lisp (indent+tabify) might do it pretty fast ...
>
> indent -kr -i8 -bri0 -l255
>
> seems to do the job even faster. I did a pile of the scsi drivers when I
> went over them. The big thing is not to mix indent with real changes.
> Its always a temptation but its vital that there are no outstanding
> changes and that a patch exists where you can test before and after
> indent to verify that change didnt cause the problems

GNU indent was broken last time I tried. When I was using it I was forced
to put its *DO NO INDENT* macros to prevent it to screwing up the code in
few places. Maybe they fixed it ...



- Davide

Re: [PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[Linus Torvalds]

On Fri, 30 May 2003, Davide Libenzi wrote:
> 
> Talking about the code, there are still a bunch of files that uses spaces
> with tabsize=4. Shouldn't those be reformatted with real TABs ? An emacs
> lisp (indent+tabify) might do it pretty fast ...

I don't generally like changing syntactic stuff without a reason.

A good reason is when the original maintainer is not that active any more,
and a new maintainer (or even just random fixer) feels that they need to
run indent on the sources in order to make them more readable before 
doign a fix.

It happens, but not very often. Alan and Al both do it to the files they 
clean up. But I don't like having it done "just because" - there should be 
a real underlying reason.

		Linus

Re: [PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[viro]

On Fri, May 30, 2003 at 03:49:12PM -0700, Linus Torvalds wrote:
> 
> On Fri, 30 May 2003, Davide Libenzi wrote:
> > 
> > Talking about the code, there are still a bunch of files that uses spaces
> > with tabsize=4. Shouldn't those be reformatted with real TABs ? An emacs
> > lisp (indent+tabify) might do it pretty fast ...
> 
> I don't generally like changing syntactic stuff without a reason.
> 
> A good reason is when the original maintainer is not that active any more,
> and a new maintainer (or even just random fixer) feels that they need to
> run indent on the sources in order to make them more readable before 
> doign a fix.
> 
> It happens, but not very often. Alan and Al both do it to the files they 
> clean up. But I don't like having it done "just because" - there should be 
> a real underlying reason.

FWIW, I'd ran Lindent maybe 10 times or so - only in truly appalling cases
when it hurts just looking at the code (drivers/block/paride, mostly - just
take a look at it in 2.4).  Usually it's more of "I change that function;
might as well reindent it" and it's done manually.

Re: [PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[Jörn Engel]

On Fri, 30 May 2003 23:55:04 +0100, viro@parcelfarce.linux.theplanet.co.uk wrote:
> 
> FWIW, I'd ran Lindent maybe 10 times or so - only in truly appalling cases
> when it hurts just looking at the code (drivers/block/paride, mostly - just
> take a look at it in 2.4).  Usually it's more of "I change that function;
> might as well reindent it" and it's done manually.

A policy that I like.  Ugly code is a big red flag that noone with
taste looked at this function in a while.  Handle with care and watch
your back.

Jörn

-- 
Fancy algorithms are buggier than simple ones, and they're much harder
to implement. Use simple algorithms as well as simple data structures.
-- Rob Pike

RE: [PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[Riley Williams]

Hi Linus.

 > The motivation for doing the ANSI-fication is just that there
 > is now a sanity checker tool that will complain loudly about
 > bad typing, and since I wrote it and I hate old-style K&R
 > sources, it doesn't parse them. 

Probably the simplest solution is to make the said tool recognise
a line like...

	#pragma KandR

...and have it abort any file where it finds that line with some
sort of warning, perhaps along the lines of...

	SanityCheck: Found K&R pragma, ignoring kernel/foobar.c

...or something similar. It would then be simply a case of adding
the said line near the top of whichever source files are still in
K&R format.

Best wishes from Riley.
---
 * Nothing as pretty as a smile, nothing as ugly as a frown.

---
Outgoing mail is certified Virus Free.
Checked by AVG anti-virus system (http://www.grisoft.com).
Version: 6.0.484 / Virus Database: 282 - Release Date: 27-May-2003

Re: [PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[Jörn Engel]

On Fri, 30 May 2003 22:40:55 +0200, Jörn Engel wrote:
> 
> I would agree with that strategy, if the zlib wasn't actively
> maintained anymore and we'd have to take over that part anyway.  But
> as it is, this will create extra work with little bonus on our side,
> except to set a better example maybe.

In related news, the kernel zlib still claims to be 1.1.3.  The
security bug fixed with 1.1.4 was a double-free problem which doesn't
apply to the kernel version anymore, but other functional changes were
missed as well.  Does anyone really understand what those changes are
about? David perhaps?

If not, I will prepare a patch.

Jörn

-- 
They laughed at Galileo.  They laughed at Copernicus.  They laughed at
Columbus. But remember, they also laughed at Bozo the Clown.
-- unknown

Re: [PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[Russell King]

On Fri, May 30, 2003 at 01:57:13PM -0600, Steven Cole wrote:
> +int foo(
> +	long bar,
> +	long day,
> +	struct magic *xyzzy
> +)

Is this really part of the kernel coding style?

-- 
Russell King (rmk@arm.linux.org.uk)                The developer of ARM Linux
             http://www.arm.linux.org.uk/personal/aboutme.html

Re: [PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[Linus Torvalds]

On Fri, 30 May 2003, Russell King wrote:
>
> On Fri, May 30, 2003 at 01:57:13PM -0600, Steven Cole wrote:
> > +int foo(
> > +	long bar,
> > +	long day,
> > +	struct magic *xyzzy
> > +)
> 
> Is this really part of the kernel coding style?

No, but it's better than what it used to be.

Also, while I don't think we should try to maintain 1:1 behaviour with 
the _worst_ offenses of zlib, I do think we should maintain comments etc, 
and a lot of the zlib function declarations used to look like

	int foo(bar, baz)
	long bar;		/* number of frobnicators */
	long baz;		/* self-larting on or off */
	{
		....

and the ANSI-fication changes this to

	int foo(
		long bar,	/* number of frobnicators */
		long baz	/* self-larting on or off */
	)
	{
		...

which while not according to the coding-standard is at least a reasonable 
compromize between having proper C function definitions and keeping the 
code _looking_ more like the original.

		Linus

Re: [PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[Steven Cole]

On Fri, 2003-05-30 at 15:17, Linus Torvalds wrote:
> On Fri, 30 May 2003, Russell King wrote:
> >
> > On Fri, May 30, 2003 at 01:57:13PM -0600, Steven Cole wrote:
> > > +int foo(
> > > +	long bar,
> > > +	long day,
> > > +	struct magic *xyzzy
> > > +)
> > 
> > Is this really part of the kernel coding style?
> 
> No, but it's better than what it used to be.
> 
> Also, while I don't think we should try to maintain 1:1 behaviour with 
> the _worst_ offenses of zlib, I do think we should maintain comments etc, 
> and a lot of the zlib function declarations used to look like
> 
> 	int foo(bar, baz)
> 	long bar;		/* number of frobnicators */
> 	long baz;		/* self-larting on or off */
> 	{
> 		....
> 
> and the ANSI-fication changes this to
> 
> 	int foo(
> 		long bar,	/* number of frobnicators */
> 		long baz	/* self-larting on or off */
> 	)
> 	{
> 		...
> 
> which while not according to the coding-standard is at least a reasonable 
> compromize between having proper C function definitions and keeping the 
> code _looking_ more like the original.
> 
> 		Linus
> 
> 
OK, here is a modified version of the patch to CodingStyle which
explicitly notes the reason for this secondary style.

Steven

--- linux/Documentation/CodingStyle.orig	2003-05-30 18:41:05.000000000 -0600
+++ linux/Documentation/CodingStyle	2003-05-30 18:46:08.000000000 -0600
@@ -149,6 +149,23 @@
 and it gets confused.  You know you're brilliant, but maybe you'd like
 to understand what you did 2 weeks from now. 
 
+Function declarations should be new-style:
+
+int foo(long bar, long baz, struct magic *xyzzy)
+
+or when replacing old-style declarations which have comments:
+
+int foo(
+	long bar,
+	long baz,
+	struct magic *xyzzy	/* essential comment */
+)
+
+Old-style function declarations are deprecated:
+
+int foo(bar, baz, xyzzy)
+long bar, baz;
+struct magic *xyzzy;		/* essential comment */
 
 		Chapter 5: Commenting
 

Re: [PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[Arnaldo Carvalho de Melo]

Em Fri, May 30, 2003 at 06:55:18PM -0600, Steven Cole escreveu:
> On Fri, 2003-05-30 at 15:17, Linus Torvalds wrote:
> > On Fri, 30 May 2003, Russell King wrote:
> > >
> > > On Fri, May 30, 2003 at 01:57:13PM -0600, Steven Cole wrote:
> > > > +int foo(
> > > > +	long bar,
> > > > +	long day,
> > > > +	struct magic *xyzzy
> > > > +)
> > > 
> > > Is this really part of the kernel coding style?
> > 
> > No, but it's better than what it used to be.
> > 
> > Also, while I don't think we should try to maintain 1:1 behaviour with 
> > the _worst_ offenses of zlib, I do think we should maintain comments etc, 
> > and a lot of the zlib function declarations used to look like
> > 
> > 	int foo(bar, baz)
> > 	long bar;		/* number of frobnicators */
> > 	long baz;		/* self-larting on or off */
> > 	{
> > 		....
> > 
> > and the ANSI-fication changes this to
> > 
> > 	int foo(
> > 		long bar,	/* number of frobnicators */
> > 		long baz	/* self-larting on or off */
> > 	)
> > 	{
> > 		...
> > 
> > which while not according to the coding-standard is at least a reasonable 
> > compromize between having proper C function definitions and keeping the 
> > code _looking_ more like the original.
> > 
> > 		Linus
> > 
> > 
> OK, here is a modified version of the patch to CodingStyle which
> explicitly notes the reason for this secondary style.

In the cases where there are documentation for the paramenters isn't it better
to just bite the bullet and use the kerneldoc style?

Documentation/kernel-doc-nano-HOWTO.txt

- Arnaldo

Re: [PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[Steven Cole]

On Fri, 2003-05-30 at 21:12, Arnaldo Carvalho de Melo wrote:
[snippage]
> > > and the ANSI-fication changes this to
> > > 
> > > 	int foo(
> > > 		long bar,	/* number of frobnicators */
> > > 		long baz	/* self-larting on or off */
> > > 	)
> > > 	{
> > > 		...
> > > 
> > > which while not according to the coding-standard is at least a reasonable 
> > > compromize between having proper C function definitions and keeping the 
> > > code _looking_ more like the original.
> > > 
> > > 		Linus
> > > 
> > > 
> > OK, here is a modified version of the patch to CodingStyle which
> > explicitly notes the reason for this secondary style.
> 
> In the cases where there are documentation for the paramenters isn't it better
> to just bite the bullet and use the kerneldoc style?
> 
> Documentation/kernel-doc-nano-HOWTO.txt
> 
> - Arnaldo
> 

Of course it would be better if code were documented in a consistent and
canonical style.  The Documentation/kernel-doc-nano-HOWTO.txt method
should probably have a one line mention in Chapter 5: Commenting, like
this:

--- linux/Documentation/CodingStyle.orig	2003-05-30 18:41:05.000000000 -0600
+++ linux/Documentation/CodingStyle	2003-05-30 22:47:55.000000000 -0600
@@ -164,7 +164,7 @@
 small comments to note or warn about something particularly clever (or
 ugly), but try to avoid excess.  Instead, put the comments at the head
 of the function, telling people what it does, and possibly WHY it does
-it. 
+it.  See Documentation/kernel-doc-nano-HOWTO.txt for details.
 
 
 		Chapter 6: You've made a mess of it


My purpose with the original patch was to canonify the unusual style
discussed above. 

The note about the old-style K&R prototypes being deprecated is probably
redundant and may be unnecessary, unless someone is copying and pasting
from some old System V code, and we all know that makes about as much
sense as Boeing secretly looking over the blueprints for the Douglas
DC-3.

Steven

Re: [PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[Michael Frank]

On Saturday 31 May 2003 13:08, Steven Cole wrote:
> The note about the old-style K&R prototypes being
> deprecated is probably redundant and may be unnecessary,
> unless someone is copying and pasting from some old
> System V code, and we all know that makes about as much
> sense as Boeing secretly looking over the blueprints for
> the Douglas DC-3.
>

Lovely :-)

Re: [PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[Bernd Eckenfels]

In article <1054342517.2901.78.camel@spc> you wrote:
> +Function declarations should be new-style:
> +
> +int foo(long bar, long baz, struct magic *xyzzy)
...

I would suggest to include the comment based linux document boiler plates
into that coding style recommendation. In that case it is clear, how you can
document the parameters of a function.

/**
 * foo: - do a foo job
 * @parameterbar: the bar parameter is used to bar
 *
 * Description: This is the long description of the function foo() which
 *   is closely related to bar()
 * section header: section description
 **/
int foo(long bar, long baz, struct magic *xyzzy)


(I am not sure about the section, and it most likely is helpful to include a
comment, that not all functions should be documented that way.

I realy think it is important to have at least a pointer from the coding
style document to the doc-comments.

Greetings
Bernd
-- 
eckes privat - http://www.eckes.org/
Project Freefire - http://www.freefire.org/

Re: [PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[Bernd Eckenfels]

In article <E19Lzpz-00011a-00@calista.inka.de> you wrote:
> /**
> * foo: - do a foo job
> * @parameterbar: the bar parameter is used to bar
> *
> * Description: This is the long description of the function foo() which
> *   is closely related to bar()
> * section header: section description
> **/
> int foo(long bar, long baz, struct magic *xyzzy)

most likely I made an error here:

/**
* foo: - do a foo job
* @bar: the bar parameter is used to bar
*
* Description: This is the long description of the function foo() which
*   is closely related to bar(). @baz may not be 0.
* section header: section description
**/

Greetings
Bernd
-- 
eckes privat - http://www.eckes.org/
Project Freefire - http://www.freefire.org/

Re: [PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[Juan Quintela]

>>>>> "linus" == Linus Torvalds <torvalds@transmeta.com> writes:

linus> On Fri, 30 May 2003, Russell King wrote:
>> 
>> On Fri, May 30, 2003 at 01:57:13PM -0600, Steven Cole wrote:
>> > +int foo(
>> > +	long bar,
>> > +	long day,
>> > +	struct magic *xyzzy
>> > +)
>> 
>> Is this really part of the kernel coding style?

linus> No, but it's better than what it used to be.

linus> Also, while I don't think we should try to maintain 1:1 behaviour with 
linus> the _worst_ offenses of zlib, I do think we should maintain comments etc, 
linus> and a lot of the zlib function declarations used to look like

linus> int foo(bar, baz)
linus> long bar;		/* number of frobnicators */
linus> long baz;		/* self-larting on or off */
linus> {
linus> ....

linus> and the ANSI-fication changes this to

linus> int foo(
linus> long bar,	/* number of frobnicators */
linus> long baz	/* self-larting on or off */
linus> )
linus> {
linus> ...

linus> which while not according to the coding-standard is at least a reasonable 
linus> compromize between having proper C function definitions and keeping the 
linus> code _looking_ more like the original.

Once there:


/**
 * foo - <put something there>
 * @bar: number of frobnicators
 * @baz: self-larting on or off
 * @userdata: pointer to arbitrary userdata to be registered
 *
 * Description: Please, fix me
 */
int foo(long bar, long baz)
{
...

Looks like a better alternative to me.

YMMV, Juan.

-- 
In theory, practice and theory are the same, but in practice they 
are different -- Larry McVoy

Re: [PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[Linus Torvalds]

On 2 Jun 2003, Juan Quintela wrote:
> 
> /**
>  * foo - <put something there>
>  * @bar: number of frobnicators
>  * @baz: self-larting on or off
>  * @userdata: pointer to arbitrary userdata to be registered
>  *
>  * Description: Please, fix me
>  */
> int foo(long bar, long baz)
> {
> ...
> 
> Looks like a better alternative to me.

Hey, if somebody were to send me a patch (hint hint), I'd happily apply 
it.

		Linus

Re: [PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[Steven Cole]

On Mon, 2003-06-02 at 09:59, Linus Torvalds wrote:
> On 2 Jun 2003, Juan Quintela wrote:
> > 
> > /**
> >  * foo - <put something there>
> >  * @bar: number of frobnicators
> >  * @baz: self-larting on or off
> >  * @userdata: pointer to arbitrary userdata to be registered
> >  *
> >  * Description: Please, fix me
> >  */
> > int foo(long bar, long baz)
> > {
> > ...
> > 
> > Looks like a better alternative to me.
> 
> Hey, if somebody were to send me a patch (hint hint), I'd happily apply 
> it.
> 
> 		Linus

I sent this last night as an example, except now the function
declaration is not wrapped.  How is this?

Steven

--- linux/lib/zlib_inflate/inftrees.c.orig	Mon Jun  2 10:15:29 2003
+++ linux/lib/zlib_inflate/inftrees.c	Mon Jun  2 10:16:47 2003
@@ -288,14 +288,16 @@
   return y != 0 && g != 1 ? Z_BUF_ERROR : Z_OK;
 }
 
+/**
+ *	zlib_inflate_trees_bits:
+ *	@uIntf *c:                19 code lengths
+ *	@uIntf *bb:               bits tree desired/actual depth
+ *	@inflate_huft * FAR *tb:  bits tree result
+ *	@inflate_huft *hp:        space for trees
+ *	@z_streamp z:             for messages
+ */
 
-int zlib_inflate_trees_bits(
-	uIntf *c,               /* 19 code lengths */
-	uIntf *bb,              /* bits tree desired/actual depth */
-	inflate_huft * FAR *tb, /* bits tree result */
-	inflate_huft *hp,       /* space for trees */
-	z_streamp z             /* for messages */
-)
+int zlib_inflate_trees_bits(uIntf *c, uIntf *bb, inflate_huft * FAR *tb, inflate_huft *hp, z_streamp z)
 {
   int r;
   uInt hn = 0;          /* hufts used in space */

Re: [PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[Arnaldo Carvalho de Melo]

Em Mon, Jun 02, 2003 at 10:39:41AM -0600, Steven Cole escreveu:
> On Mon, 2003-06-02 at 09:59, Linus Torvalds wrote:
> > On 2 Jun 2003, Juan Quintela wrote:
> > > 
> > > /**
> > >  * foo - <put something there>
> > >  * @bar: number of frobnicators
> > >  * @baz: self-larting on or off
> > >  * @userdata: pointer to arbitrary userdata to be registered
> > >  *
> > >  * Description: Please, fix me
> > >  */
> > > int foo(long bar, long baz)
> > > {
> > > ...
> > > 
> > > Looks like a better alternative to me.
> > 
> > Hey, if somebody were to send me a patch (hint hint), I'd happily apply 
> > it.
> > 
> > 		Linus
> 
> I sent this last night as an example, except now the function
> declaration is not wrapped.  How is this?
> 
> Steven
> 
> --- linux/lib/zlib_inflate/inftrees.c.orig	Mon Jun  2 10:15:29 2003
> +++ linux/lib/zlib_inflate/inftrees.c	Mon Jun  2 10:16:47 2003
> @@ -288,14 +288,16 @@
>    return y != 0 && g != 1 ? Z_BUF_ERROR : Z_OK;
> +int zlib_inflate_trees_bits(uIntf *c, uIntf *bb, inflate_huft * FAR *tb, inflate_huft *hp, z_streamp z)
>  {
>    int r;
>    uInt hn = 0;          /* hufts used in space */

I do it like this:


int zlib_inflate_trees_bits(uIntf *c, uIntf *bb, inflate_huft * FAR *tb,
			    inflate_huft *hp, z_streamp z)

- Arnaldo

Re: [PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[Steven Cole]

On Mon, 2003-06-02 at 11:34, Arnaldo Carvalho de Melo wrote:
> Em Mon, Jun 02, 2003 at 10:39:41AM -0600, Steven Cole escreveu:
> > On Mon, 2003-06-02 at 09:59, Linus Torvalds wrote:
> > > On 2 Jun 2003, Juan Quintela wrote:
> > > > 
> > > > /**
> > > >  * foo - <put something there>
> > > >  * @bar: number of frobnicators
> > > >  * @baz: self-larting on or off
> > > >  * @userdata: pointer to arbitrary userdata to be registered
> > > >  *
> > > >  * Description: Please, fix me
> > > >  */
> > > > int foo(long bar, long baz)
> > > > {
> > > > ...
> > > > 
> > > > Looks like a better alternative to me.
> > > 
> > > Hey, if somebody were to send me a patch (hint hint), I'd happily apply 
> > > it.
> > > 
> > > 		Linus
> > 
> > I sent this last night as an example, except now the function
> > declaration is not wrapped.  How is this?
> > 
> > Steven
> > 
> > --- linux/lib/zlib_inflate/inftrees.c.orig	Mon Jun  2 10:15:29 2003
> > +++ linux/lib/zlib_inflate/inftrees.c	Mon Jun  2 10:16:47 2003
> > @@ -288,14 +288,16 @@
> >    return y != 0 && g != 1 ? Z_BUF_ERROR : Z_OK;
> > +int zlib_inflate_trees_bits(uIntf *c, uIntf *bb, inflate_huft * FAR *tb, inflate_huft *hp, z_streamp z)
> >  {
> >    int r;
> >    uInt hn = 0;          /* hufts used in space */
> 
> I do it like this:
> 
> 
> int zlib_inflate_trees_bits(uIntf *c, uIntf *bb, inflate_huft * FAR *tb,
> 			    inflate_huft *hp, z_streamp z)
> 
> - Arnaldo

For zlib, here is a worst case, with three choices, and there may be
others since style is quite a matter of taste.

local int huft_build(uIntf *b, uInt n, uInt s, const uIntf *d, const uIntf *e,
		     inflate_huft * FAR *t, uIntf *m, inflate_huft *hp, uInt *hn, uIntf *v)

local int huft_build(uIntf *b, uInt n, uInt s, const uIntf *d, const uIntf *e,
	inflate_huft * FAR *t, uIntf *m, inflate_huft *hp, uInt *hn, uIntf *v)

local int huft_build(uIntf *b, uInt n, uInt s, const uIntf *d, const uIntf *e, inflate_huft * FAR *t, uIntf *m, inflate_huft *hp, uInt *hn, uIntf *v)

Steven

Re: [PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[Jörn Engel]

On Mon, 2 June 2003 10:39:41 -0600, Steven Cole wrote:
> 
> I sent this last night as an example, except now the function
> declaration is not wrapped.  How is this?

Good.  Would be even better if the long line were wrapped.

Jörn

-- 
Do not stop an army on its way home.
-- Sun Tzu

Re: [PATCH] 2.5 Documentation/CodingStyle ANSI C function declarations.

[Arnaldo Carvalho de Melo]

Em Mon, Jun 02, 2003 at 08:59:39AM -0700, Linus Torvalds escreveu:
> 
> On 2 Jun 2003, Juan Quintela wrote:
> > 
> > /**
> >  * foo - <put something there>
> >  * @bar: number of frobnicators
> >  * @baz: self-larting on or off
> >  * @userdata: pointer to arbitrary userdata to be registered
> >  *
> >  * Description: Please, fix me
> >  */
> > int foo(long bar, long baz)
> > {
> > ...
> > 
> > Looks like a better alternative to me.
> 
> Hey, if somebody were to send me a patch (hint hint), I'd happily apply 
> it.

Hey, I'm doing this for all the parts of the net/ (and others) I touch 8)
Now we need a docbook volunteer to see if everything is going to be used
by make docs.

- Arnaldo