Source Documentation
Introduction
SVEditor supports Natural Docs style commenting of code. What does this give me?
- A commenting style that is reasonably easy to sell to your peers
- Provides pop-ups as you mouse over code
- Mousing over a module, variable or function name will automatically bring up the text that the user added as he documented his code
- Allows you to create a reference guide for the verification collateral that you have created.
- No more maintaining a separate word document that describes your class structure
- Keep your code accurately documented, hit "Generate", Select the packages you want to generated documentation for and Viola
First Example
/** * Package: another_pkg * * This is another_pkg a package for tinkering with SVEditors doc commenting * to test package selection from the wiz. * */
package another_pkg;
// class: another_pkg_class // // This is another_pkg_class. And it is simple. // Note that I am using // instead of /*...*/ // class another_pkg_class ;
/**
* Variable: var_a
*
* This is a variable
*/
rand bit var_a;
/**
* Variable: var_b
*
* This is a random variable var_b, see also <var_a>
*/
rand bit var_b;
/**
* Function: mult
*
* Multiply two numbers
* (start code)
* output = x * y;
* (end)
*
* See Also:
* <div>
*/
function mult ();
endfunction
/**
* Function: div
*
* Divide 2 numbers.
*
* (start diagram)
*
* D +----+ Q
* ----| |-----
* clk | |
* ----|> |
* +----+
*
* (end)
*
* See Also:
* <mult>
*/
function div ();
endfunction
endclass
endpackage
Generating Documentation
First step is to make sure the code is complete. The documentation generator extracts comments not right at generation, but when the SV Index is built. Force a rebuild by Right-Click on Project in Project Explorer>Rebuild SV Index.
Next step start the document generator by clicking on the blue "Generate Docs" icon on the toolbar.
Select the packages you want documentation generated for.
Select the output directory.
Hit finish and enjoy your handiwork.
