VHDL document generation utilities

for free, have a look at this:

example

I haven't used it, but I like the idea of postprocessing rather than preprocessing the code. Keep in mind that the customer for this kind of documentation is the user or customer of the hdl design, not the author.

Some developers are fussy about their front-end tools and might lack motivation to adopt the more restrictive documentation systems like mentor hdl designer. A developer would probably prefer a working testbench to a binder full of documents in any case.

-- Mike Treseler

Un bel giorno MM digitò:

The almighty Doxygen now supports also VHDL:

or

I've used the following document extraction tools:

NaturalDocs Robodoc

Both do not natively support VHDL, but can be configured to extract decent documentation. See

Hi believe that doxygen now supports VHDL (although I have never actually used it with VHDL).

I have briefly used it for S/W (where it is widely used) and find it quite useful (especially the call graphs.

Steven

Steven

Anyone using such a utility on my watch is fired immediately. Proper documentation describes the idea behind an implementation. Tools like doxygen produce nice looking documents, but the contents of the documents are useless because the idea behind it all is missing.

I like to demonstrate this "idea behind it all" in working and well-commented testbench procedures. It is a rare exception when anyone other than the developers care about this level of detail.

...and, if I ever have to work for Nico, I will at least make it through the first day. (but probably not much longer ;)

-- Mike Treseler

One problem with commented testbench procedures though is that those procedures are only testing the certain subset of conditions under which the thing has been tested and verified which is many times a subset of the entire ways that the design will actually operate out in the wild.

If you follow the test driven development methodology then your testbench (and therefore the commented code) will be created first before the design so it would be available to the other developers. If you create the design first and then the testbench for that design, then the documentation for those other developers might not be ready when they need it when performing concurrent design.

Personally, I prefer creating a design specification. High level design and architectural decisions are made before design or testbench code gets written, putting those decisions into some tangible form and keeping that document up to date are not that hard to do. Plus, by creating such documentation, you can have actual live links to reference information that would be useful to whoever it is that would read the document.

After the fact documentation is always tedious, dull and nearly pointless. Presumably 'somebody' needs information on how your design is supposed to work so that they can create their design so that the two can be integrated into a final system (unless of course that 'somebody' is yourself). So, except for the one man show, this after the fact documentation is almost guaranteed to be too late so even if the only audience is the developers, those developers do need the info, they need it in a timely manner to do their part and unless you like to answer phone/e-mails regarding how it eventually will work (and probably giving conflicting answers over the time period that you're creating the design), the design spec provides the common ground for all, filling it out more of the details as one goes along, gives everybody the up to date info that they need to do their job.

Using a tool to extract this information after the fact is generally more work than to have simply put that exact same information into a design specification.

Ya might've even missed out on the interview ;)

Kevin Jennings

When used to its full extent, doxygen allows you to produce all sorts of documents - not just syntax-highlighted source code printouts. You can have files that are used purely for documentation, and include all the usual features of technical documents (structure layout, images, graphs, cross-references, company logos, or whatever) - it's not really any different than using a tool such as LaTeX for your documentation. You can cross-link to source code as and when required, of course.

If you just mean that running a typical loosely commented set of source code files through doxygen and calling it "the project's complete documentation" is a fireable offence, then your comments make much more sense.

The idea behind a design is where it all starts. Why is the design the way it is? Answers to these questions are required to make meaningfull extensions to a design which don't break other parts.

In practise a simple block diagram which shows how the information flows through the different blocks (something you'll never ever get out of doxygen et al) says way more than a doxygen print-out.

Anyone can pull a piece of source through doxygen but a good IDE (like Eclipse) provides the same information real-time.

Mr. Coesel posted on Thu, 27 Mar 2008 17:05:02 GMT: |---------------------------------------------------------------------| |"Anyone using such a utility on my watch is fired immediately. Proper| |documentation describes the idea behind an implementation. Tools like| |doxygen produce nice looking documents, but the contents of the | |documents are useless because the idea behind it all is missing." | |---------------------------------------------------------------------|

Do you think that perhaps you overreacted?

Regards, N. C. P. Gloster