The vzDoc Manual

Verilab Ltd.

1. Using vzDoc

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 top.vr (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 browser.

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.