VHDL document generation utilities

Hi all,

I was wondering if there is a good VHDL document generation utility (free or 
not) out there? I stumbled across an article describing HDLDoc by DualSoft, 
which seemed promising, but it seems that that company ceased to exist... I 
am looking for something that would be more than just a comments 
extractor...


Thanks,
/Mikhail 

> I was wondering if there is a good VHDL document generation utility (free or 
> not) out there? I stumbled across an article describing HDLDoc by DualSoft, 
> which seemed promising, but it seems that that company ceased to exist... I 
> am looking for something that would be more than just a comments 
> extractor...

I use vhdldoc: http://schwick.home.cern.ch/schwick/vhdldoc/Welcome.html

YMMV
-P@

MM wrote:

> I was wondering if there is a good VHDL document generation utility (free or 
> not) out there? I stumbled across an article describing HDLDoc by DualSoft, 
> which seemed promising, but it seems that that company ceased to exist... I 
> am looking for something that would be more than just a comments 
> extractor...

for free, have a look at this:

example
http://schwick.web.cern.ch/schwick/muctpi/mirod/mirod.html
download
http://schwick.home.cern.ch/schwick/vhdldoc/Welcome.html

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�:

> I was wondering if there is a good VHDL document generation utility (free or 
> not) out there? I stumbled across an article describing HDLDoc by DualSoft, 
> which seemed promising, but it seems that that company ceased to exist... I 
> am looking for something that would be more than just a comments 
> extractor...

The almighty Doxygen now supports also VHDL:

http://www.stack.nl/~dimitri/doxygen/
http://www.stack.nl/~dimitri/doxygen/docblocks.html#vhdlblocks

-- 
emboliaschizoide.splinder.com

On Mar 26, 10:23=A0am, "MM" <mb...@yahoo.com> wrote:
> Hi all,
>
> I was wondering if there is a good VHDL document generation utility (free =
or
> not) out there? I stumbled across an article describing HDLDoc by DualSoft=
,
> which seemed promising, but it seems that that company ceased to exist... =
I
> am looking for something that would be more than just a comments
> extractor...
>
> Thanks,
> /Mikhail

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 http://en.wikipedia.org/wiki/Comparison_of_documentation_generators

On 26 Mar, 18:23, "MM" <mb...@yahoo.com> wrote:
> Hi all,
>
> I was wondering if there is a good VHDL document generation utility (free or
> not) out there? I stumbled across an article describing HDLDoc by DualSoft,
> which seemed promising, but it seems that that company ceased to exist... I
> am looking for something that would be more than just a comments
> extractor...
>
> Thanks,
> /Mikhail

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

"MM" <mbmsv@yahoo.com> wrote:

>Hi all,
>
>I was wondering if there is a good VHDL document generation utility (free or 
>not) out there? I stumbled across an article describing HDLDoc by DualSoft, 
>which seemed promising, but it seems that that company ceased to exist... I 
>am looking for something that would be more than just a comments 
>extractor...

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.

-- 
Programmeren in Almere?
E-mail naar nico@nctdevpuntnl (punt=.)

Nico Coesel wrote:

> 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

"Mike Treseler" <mike_treseler@comcast.net> wrote in message 
news:65241lF2dqaavU1@mid.individual.net...
> Nico Coesel wrote:
>
>> 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.
>

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.

<soapbox>
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.

</soapbox>

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

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

Kevin Jennings 

Nico Coesel wrote:
> "MM" <mbmsv@yahoo.com> wrote:
> 
>> Hi all,
>>
>> I was wondering if there is a good VHDL document generation utility (free or 
>> not) out there? I stumbled across an article describing HDLDoc by DualSoft, 
>> which seemed promising, but it seems that that company ceased to exist... I 
>> am looking for something that would be more than just a comments 
>> extractor...
> 
> 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.
> 

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.