Tool for VHDL/Verilog code documentation

[Altera_Forum]

Hi,  

 Can someone share experience on writing documentation for FPGA design? How do you write it?    I want to write documentation for FPGA project, describe which top modules are responsible for what, and main source files should also be documented.  The main purpose of this documentation should be that other designer can easily take and modify my project or quickly understand structure of my project.    I have found some tools for creating documentation like Doxygen and Sigasi. But Doxygen has only few features to support VHDL language and Sigasi is not free tool.    Thanks

[Altera_Forum]

Usually, we write word documentation showing the architecture and interfaces, design decision etc.

[Altera_Forum]

--- Quote Start ---  Usually, we write word documentation showing the architecture and interfaces, design decision etc.  --- Quote End ---    Hi, Tricky  Can I ask you to share some examples? Or could you point me where to find good detailed FPGA project documentation? Because now i dont have any ideas from where to start.  I have googled for documents which describes whole FPGA design but did not find anything except small readme files for separate VHDL files.

[Altera_Forum]

I cant share because they are all protected company documents. 

Usually, the document contains:  1. Reasons for the project 2. The interfaces used and why 3. The overall architecture and design functionality 4. Interface descriptions, including block to block port map, CPU register map etc. 5. Test plan, including the testbenches required, the tests required, and the hardware tests required. 6. The estimated resource usage  And this should all be written and reviewed before you write much/any HDL (obviously it should be updated as things change during the implementation, as they inevitably will)

[Altera_Forum]

Apart from writing a high level description (text, not code) of the system in word or similar programs, I also include a short behavioural description in the first few lines of each source file. 

If that is a package I write the reason for that package. Most of the time I also include one or more block diagrams in the high level description.

[Altera_Forum]

Thank you for your answers (Tricky, PietervanderStar). 

 So there is no other popular solution to document projects apart from writing word documents?

[Altera_Forum]

--- Quote Start ---  Thank you for your answers (Tricky, PietervanderStar).  So there is no other popular solution to document projects apart from writing word documents?  --- Quote End ---    Some people use libreoffice (because it's free). This is a cool website for drawing wave diagrams:  http://wavedrom.com/  Use Visio for other diagrams.  Documentation is engineers bugbear. They hate creating it, and hate it when other engineers havent created it.

[Altera_Forum]

Inaddition to Trickys reply, most of "us engineers" don't mind how itnis written as long as it is clear and easy to understand.