1
0
mirror of https://git.FreeBSD.org/src.git synced 2024-12-24 11:29:10 +00:00
freebsd/tools/kerneldoc/subsys/README
Alexander Leidinger ff4b8cb7bd This is the kernel subsystem API documentation generation framework.
It uses doxygen to generate the API documentation. For each subsystem
a very small (about 20 lines with comments) subsystem specific Doxyfile
has to be written (have a look at the README for more). All common doxygen
options are specified in a separate file.

The framework is configured to not only generate the HTML version, but also
a PDF version (the paper size is hardcoded to DIN A4 currently and depending
on the subsystem you have to increase some limits in the latex configuration
of your system, the README tells more about this).

It also allows cross-references between the subsystems (it generates doxygen
tag files).

Currently the docs are generated in OBJDIR, but this may change after
coordination with doc@. The makefile is prepared to generate/move various
parts of the generated docs to different destinations.

TARGET_ARCH is respected and some env-vars are set for architecture specific
handling of the source (the README tells more).

Subsystems for which docs are generated:
 - cam                  - crypto                - dev_pci
 - dev_sound            - dev_usb               - geom
 - i4b                  - kern                  - libkern
 - linux                - net80211              - netgraph
 - netinet              - netinet6              - netipsec
 - opencrypto           - vm

Requested by:	gnn
2006-05-26 18:06:07 +00:00

33 lines
1.2 KiB
Plaintext

The kernel subsystem API documentation generation framework.
--------------------------------------------------------------
For every Doxyfile-(.*) the Makefile adds the public targets $1, pdf-$1 and
clean-$1. For e.g. Doxyfile-dev_pci this translates to the targets dev_pci,
pdf-dev_pci and clean-dev_pci.
Additionally, the targets 'all', 'pdf-all' and 'clean' to generate or remove
the documentation for all targets are available.
The file 'Dependencies' contains dependencies for the .tag files.
To add another part to the documentation just copy a Doxyfile and add
the necessary dependencies to the file 'Dependencies'.
The following environment variables can be used in the Doxyfile:
- DOXYGEN_SRC_PATH (/usr/src/sys)
- DOXYGEN_DEST_PATH (where the docs are generated)
- DOXYGEN_TARGET_ARCH (${TARGET_ARCH} if set, else ${MACHINE_ARCH})
For the PDF generation you may have to change some limits in the latex
configuration (the build may fail and an error about e.g. "pool size" is
shown), for print/teTeX this is done in
/usr/local/share/texmf/web2c/texmf.cnf
Programs needed to generate the API docs:
- devel/doxygen
- print/teTeX
- graphics/graphviz
--
$FreeBSD$