VHDL document generation utilities

[MM]

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

 

[PatC]

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@

 

[Mike Treseler]

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

 

[Reuven]

On Mar 26, 10:23 am, "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

 

[Nico Coesel]

"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=.)

 

[Mike Treseler]

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

 

[KJ]

"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

 

[David Brown]

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.

 

[Nico Coesel]

Mike Treseler <mike_treseler@comcast.net> wrote:

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.

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.

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

 

[Colin Paul Gloster]

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