VHDL document generation utilities

Discussion in 'VHDL' started by PatC, Mar 26, 2008.

  1. PatC

    PatC Guest

    > 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@
    PatC, Mar 26, 2008
    #1
    1. Advertising

  2. PatC

    MM Guest

    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
    MM, Mar 26, 2008
    #2
    1. Advertising

  3. 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
    Mike Treseler, Mar 26, 2008
    #3
  4. PatC

    Reuven Guest

    On Mar 26, 10:23 am, "MM" <> 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
    Reuven, Mar 26, 2008
    #4
  5. PatC

    Guest

    On 26 Mar, 18:23, "MM" <> 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
    , Mar 27, 2008
    #5
  6. PatC

    Nico Coesel Guest

    "MM" <> 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, Mar 27, 2008
    #6
  7. 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, Mar 27, 2008
    #7
  8. PatC

    KJ Guest

    "Mike Treseler" <> wrote in message
    news:...
    > 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
    KJ, Mar 27, 2008
    #8
  9. PatC

    David Brown Guest

    Nico Coesel wrote:
    > "MM" <> 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.
    David Brown, Mar 28, 2008
    #9
  10. PatC

    Nico Coesel Guest

    Mike Treseler <> 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=.)
    Nico Coesel, Mar 28, 2008
    #10
  11. 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
    Colin Paul Gloster, May 23, 2008
    #11
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. _eee_
    Replies:
    3
    Views:
    472
    Rick Strahl [MVP]
    Feb 28, 2004
  2. Ganesh
    Replies:
    4
    Views:
    361
    Thomas Weidenfeller
    Jan 31, 2005
  3. Marcus Leon

    Ant Utilities?

    Marcus Leon, Feb 4, 2005, in forum: Java
    Replies:
    1
    Views:
    665
    Bryce
    Feb 4, 2005
  4. afd
    Replies:
    1
    Views:
    8,234
    Colin Paul Gloster
    Mar 23, 2007
  5. John W. Long

    HTML Generation (Next Generation CGI)

    John W. Long, Nov 22, 2003, in forum: Ruby
    Replies:
    4
    Views:
    308
    John W. Long
    Nov 24, 2003
Loading...

Share This Page