[proposition of drivers documentation]

[xosé vázquez pérez]

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 <[e-mail]> or/and <[e-mail]>
 [date]: 00:00:00 11/12/1969
 [license]: BSD/GPL/dual GPL-BSD

 [maintainer]: Name <[e-mail]> or/and <[e-mail]>
 [bugs]: <[e-mail]> or/and Name <[e-mail]>
 [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 #] [<[e-mail]>]
 - 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.