[proposition of drivers documentation]

hi guys,

to try to avoid lost bug fixed and situations like this thread:
http://marc.theaimsgroup.com/?t=104327599900004&r=1&w=2
and to get more information about drivers/hardware duet.

I propose to include in every main driver file( but it can be extensive to other files):

notes:
- [] _mandatory_
- dates and times are in _UTC_

fields are trivial but some need an explication:

- [modification #]: necessary because not all people change the driver version every time it's made a modification. It's _mandatory_ change it when you touch the file. And always it's relative to _official kernel_ version that you have modified plus 1.
- [quality]: there are very basic drivers, they works but they don't have manufacturer support or documentation. They are good to play but not for high servers because they lack of higher features or performance.

/*
=HEADER

[name]: foo bar adapters family
[author]: Name <[email protected]> or/and <[email protected]> [date]: 00:00:00 11/12/1969
[license]: BSD/GPL/dual GPL-BSD

[maintainer]: Name <[email protected]> or/and <[email protected]> [bugs]: <[email protected]> or/and Name <[email protected]> [kernel_version]: >2.5.49 2.4.21
[state]: stable/devel/unstable or 1/2/3
[quality]: high/medium/low or 1/2/3
[version]: 00.00.00
[date]: 00:00:00 01/01/2001
[modification #]: AAA00001
url_info: http://www.server.com/hacker/my-driver-info/
url_down: ftp://ftp.server.com/pub/drivers/linux/
mailing-list: if clouse url or <e-mail> to subscribe or real <e-mail> cvs:

=END
*/

/*
=CHANGELOG

[Changelog]: (latest at top)

[date] [version] or [modification #] [<[email protected]>]
- bug fixes at makemelove()
...

=END
*/

/*
=HARDWARE

[Supported hardware]:

[manufacturer_1]
[product name]

[manufacturer_2]
[product name]

=END
*/

/*
=NOTES

notes:

Hardware was designed by acme labs and it works like a sex machine. You need update firmware to XXX version because it
has a lots of fuck*d hardware problems and ...

=END
*/

and in the other driver files (*.c or *.h )

/*

[license]: BSD/GPL/dual GPL-BSD
[modification #]: AAA00080
[depends]: midriver.c

*/

It would be possible to put tags or something to make marks and to extract documentation about drivers and supported hardware like perl auto-documented files.
It will make easier the linux vendors work.

Another idea is to put under Documentacion/ the same tree than the kernel files, to move all README.* CHANGELOG.* inside this tree. And to change the name to a more standard like driver-name.readme and driver-name.changelog

There are too much chaos and sometimes it is very hard to find real information and updated. Because LiNUX hasn't a perpetual kernel team and people go and come ;-)

IMHO.

-thank you for to read this-

regards,

Software is like sex, it's better when it's bug free.

This starts to get very long over time, and quite messy, and pretty much is pointless. I used to do it for my drivers, but have given up due to no one ever reading it, and the advent of bitkeeper (you can get individual revision history for every file now quite easily.)

This is already listed in the MODULE_DEVICE_TABLE and can be parsed later by userspace tools quite easily.

thanks,

greg k-h