VHDocL - a VHDL documentation utility
In the software world, documentation tools abound. Doxygen, javadoc, kdoc and others allow to extract specially formatted comments from source code and generate a set of interlinked HTML pages giving the annotated class structure of the program.
VHDocL serves to document a hardware design at the structural level. Signals, formulas, function bodies and other functional components of the source code are ignored. Entities and architectures, function declarations, constants, processes, instantiations, generate statements and other constructs relating to the structure of the design are parsed and documented in HTML pages. As with other documentation generators, the code can be annotated with special comments which will be added to the HTML documentation.
The HTML ouput is interlinked extensively: instantiations are linked to the declaration of the component and to the entity to which it is bound. Bindings are determined across libraries if necessary and taking for...use statements into account. VHDocL also supports configurations.
From a presentational point of view, the generated documentation can be customised by a CSS style sheet file provided by the user, and by up to two logos displayed on every page.
VHDocL has been tested on a number of open-source designs and is being used on FPGA designs by me and by colleagues as well as larger ASIC designs. It is considered stable enough to be unleashed on an unsuspecting community of VHDL coders.
Features blurb
- Documents entities, architectures, configurations and packages and their
declarations, processes and instantiations
- HTML tags and images allowed in descriptions
- Collective descriptions for groups of ports, generics or constants
- Corporate identity appearance through optional logos and style file
- Source code syntax highlighting, customisable by user style file
- Supports attributes, configurations and multiple libraries
- Component instantiations resolved, taking into account for...use
statements and configurations
- Partial support for Accelera's Property Specification Language (PSL)
- Supports versioning information substituted by Subversion version
management system
Recent improvements:
- Syntax highlighting by CSS classes, allowing user customisation
- The parsing and processing runtime has been greatly reduced in version 0.2
- Clearer presentation through hierarchical instantiation view and syntax highlighting
|
