>Number:         6420
>Category:       kern
>Synopsis:       Lack of source code documentation.
>Confidential:   no
>Severity:       non-critical
>Priority:       high
>Responsible:    kern-bug-people (Kernel Bug People)
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Mon Nov  9 16:20:00 1998
>Last-Modified:
>Originator:     Lloyd Parkes
>Organization:
Lloyd Parkes, soon to be ex-Postmaster and ex-Hostmaster for Victoria University
 "Feed me!" - Audrey II
>Release:        NetBSD-1.3.2
>Environment:
	
System: NetBSD whau.its.vuw.ac.nz 1.3.2 NetBSD 1.3.2 (Deskpro) #0: Fri Nov 6 11:59:32 NZDT 1998 lloyd@whau.its.vuw.ac.nz:/usr/src/NetBSD/NetBSD-1.3.2/sys/arch/i386/compile/Deskpro i386


>Description:
The quality of the comments in the source code is very poor. IMHO it
is below modern standards for published source code.

>How-To-Repeat:

Read the file /usr/src/sys/dev/ic/am79900.c and try and work out what
sort of device this code supports.

>Fix:

Read some of the Linux source code (but only some). The add on PCMCIA
support for Linux contains the file
pcmcia-cs-3.0.5/clients/nmclan_cs.c which starts with the following
comment.


/* ----------------------------------------------------------------------------
Linux PCMCIA ethernet adapter driver for the New Media Ethernet LAN.
  nmclan_cs.c,v 0.16 1995/07/01 06:42:17 rpao Exp rpao

  The Ethernet LAN uses the Advanced Micro Devices (AMD) Am79C940 Media
  Access Controller for Ethernet (MACE).  It is essentially the Am2150
  PCMCIA Ethernet card contained in the the Am2150 Demo Kit.

Written by Roger C. Pao <rpao@paonet.org>
  Copyright 1995 Roger C. Pao

  This software may be used and distributed according to the terms of
  the GNU Public License.

Ported to Linux 1.3.* network driver environment by
  Matti Aarnio <mea@utu.fi>

References

  Am2150 Technical Reference Manual, Revision 1.0, August 17, 1993
  Am79C940 (MACE) Data Sheet, 1994
  Am79C90 (C-LANCE) Data Sheet, 1994
  Linux PCMCIA Programmer's Guide v1.17
  /usr/src/linux/net/inet/dev.c, Linux kernel 1.2.8

  Eric Mears, New Media Corporation
  Tom Pollard, New Media Corporation
  Dean Siasoyco, New Media Corporation
  Ken Lesniak, Silicon Graphics, Inc. <lesniak@boston.sgi.com>
  Donald Becker <becker@cesdis1.gsfc.nasa.gov>
  David Hinds <dhinds@hyper.stanford.edu>

  The Linux client driver is based on the 3c589_cs.c client driver by
  David Hinds.

  The Linux network driver outline is based on the 3c589_cs.c driver,
  the 8390.c driver, and the example skeleton.c kernel code, which are
  by Donald Becker.

  The Am2150 network driver hardware interface code is based on the
  OS/9000 driver for the New Media Ethernet LAN by Eric Mears.

  Special thanks for testing and help in debugging this driver goes
  to Ken Lesniak.


-------------------------------------------------------------------------------
Driver Notes and Issues
-------------------------------------------------------------------------------

1. ...

-------------------------------------------------------------------------------
History
-------------------------------------------------------------------------------
Log: nmclan_cs.c,v
 * Revision 0.16 ...

The source code is interspersed with numerous useful comments about
how the device operates and why things were done the way they were. If
I manage to document my code half as well as this I will be pleased.

If I manage to write some documentation in my Copious Free Time(tm), I will of course send it in.
>Audit-Trail:
>Unformatted: