vzDoc is a tool from Verilab to generate API documentation from Specman/e or Vera source code. Specially formatted comments (“doc-comments”) in the source code provide some of the API information.
Before using vzDoc, you may need to consider its license (Licensing), its installation (if not already done: Installation), the support available (Section 4.2, “Support for vzDoc”), the vagaries of this particular release (Section 2, “Release notes: current release (0.4.4)”), and/or the shortcomings of vzDoc in general (Section 3, “Limitations and bugs: general (both languages)”).
If you're still keen to go (and why not?), and you have a source file
top.e (Specman/e) or
(Vera), try one of:
vzdoc top.e vzdoc top.vr
(The file that you normally tell vzDoc about is the top-level of the module hierarchy; it will dig down and find the rest.)
After either invocation, you should find an HTML presentation in
vzDoc/index.html, which you may view with any Web
You may affect vzDoc's behaviour with its command-line options and environment variables (Section 2, “Invoking vzDoc”); and by adding special “doc-comments” to your source code (Section 3, “Adding documentation to your code”).
Benefits of vzDoc include:
The resulting browsable documentation is a powerful presentation method for code reviews, walkthroughs, reference and training.
It encourages accurate documentation of APIs through useful and valuable commenting.
It is easy to use as part of the code build/release process. Code and documentation released from the same source at the same time are more likely to agree.