Hey Luc,

I personally have two main forms of documentation for a design. The first is a specification that is written using a word processor and is completely separate from the VHDL code. In this document I explicitly highlight all major design features, starting at the top level and drilling down to block level and unit levels. The purpose of this is to detail the theory of operation and to not clutter up the VHDL files. In addition, this document also contain any important interfaces that are external to the device (ASIC/FPGA/CPLD/etc.)

The second form of documentation is in the VHDL files and is typically inline with the hdl. I try to create process names that are self documenting (ie calculate_agc: process (clk, rst) is ...). If the name isn't self-documenting, I'll give a short description of what the process is immediately before the process. I follow the same methodology for variables, signals, ports, constants, sub programs, etc. It's important to write clear code and to add inline comments, especially when you're doing something that isn't immediately self evident.

For the first form of documentation, I'll spend a lot of time up front documenting something (sometimes weeks, if not over a month). This forces me to think about the design and any potential issus that may arrise. It also allows me to pass a particular block off to someone else pretty quickly if I find myself not being able to finish everything on time.

For the inline documentation, I don't really know how much time I spend documenting. I just do it. In other words, while I'm writing my VHDL code, I'm also placing the comments in there. So I guess it takes me however long it takes to write a comment! This is probably the best way to document inline since you're in the right frame of mind when writing VHDL.

Regarding tools -- I use Sigasi HDT for all my VHDL editing and code management. I don't have any specific tool for documenting inline. However, it would be nice to create a VHDL-doc, something that is similar to Javadoc so the documentation could automatically be "rolled up".

Not sure if this helps. Good luck with your design.

Larry

Hi Luc, thanks for opening this discussion. I've created a poll and I'll share the results.