Hi...
The attached patch for scripts/kernel-doc adds the following features:
1. You can document structs, unions, enums and typedef like this:
/**
* enum driver_type - Describes the type of a driver
* @DRIVER_TYPE_DEVICE: driver controls a device (like fd.o)
* @DRIVER_TYPE_BUS: driver manages a bus (like usbcore.o)
*
* Some description.
*/
enum driver_type {
DRIVER_TYPE_DEVICE = 0,
DRIVER_TYPE_BUS = 1,
};
/**
* struct pci_device_id - identification of a pci device
* @vendor: Vendor ID or %PCI_ANY_ID
* @device: Device ID or %PCI_ANY_ID
*
* bla bla bla (description)
*/
struct pci_device_id {
unsigned int vendor;
unsigned int device;
};
/**
* typedef uint32 - unsigned integer.
* Description of an unsigned integer.
*/
typedef unsigned int uint32;
The parser is currently not able to handle comma-separated declarations in
structs or unions ("int a,b;"). Only those struct members that you have
declarated will appear in the documentation - this is intended and allows you
to have undocumented members. Similarly the actual type of a typedef'd type
is not contained in the documentation.
2. Added some support for a new section called "Context" that should be used
to describe the context in which a function can be invoked. The section can
be declared together with the arguments, terminated by an empty line (unlike
regular sections). The Context section should make it easier for the reader
to find out, for example, whether a function can be called from a interrupt.
I would propose to use a simple sytax based on the functions in_interrupt(),
in_irq() and in_softirq(). If a function can only be called in user-context
write "!in_interrupt()", if a function can only be called from a software irq
level write "in_softirq()" and so on. For functions that can be called
everywhere write "all contexts". Example:
/**
* usb_deregister - unregister a USB driver
* @driver: USB operations of the driver to unregister
* Context: !in_interrupt()
*
* Unlinks the specified driver from the internal USB driver list.
*/
void usb_deregister(struct usb_driver *driver);
3. Many minor fixes, for example the date of generated man pages isn't
hard-coded anymore and some regular expressions worked only with spaces in
declarations (but not with tabs), this has been fixed.
Known problems:
- due to my lack of understanding of troff(?) the generated man pages need
some improvements.
This archive was generated by hypermail 2b29 : Sun Sep 30 2001 - 21:00:39 EST