New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Significant loss of functionality in v1.7.6.1 for VHDL builds (Origin: bugzilla #666088) #4502

Closed
doxygen opened this Issue Jul 2, 2018 · 0 comments

Comments

Projects
None yet
1 participant
@doxygen
Owner

doxygen commented Jul 2, 2018

status RESOLVED severity normal in component general for ---
Reported in version 1.7.6.1 on platform Other
Assigned to: Dimitri van Heesch

Original attachment names and IDs:

On 2011-12-13 14:33:45 +0000, Tim James wrote:

Created attachment 203342
Example VHDL source file, project file and v1.7.5.1 and v1.7.6.1 CHM builds

Doxygen has proved invaluable in a number of recent projects for generating useful documentation for FPGA designs implemented using VHDL. Unfortunately, there appears to have been a significant loss of functionality in the newly released v1.7.6.1 of the tool:

  1. The ability to 'remotely' document objects, eg, use the \class keyword to enable the documentation/description of a VHDL entity to be located in the file header, doesn't appear to work. (Incidentally there appear to have been various restrictions to this for some time, eg, don't appear to be able to relocate the documentation of a constant in a package, just now it's even more broken).

  2. Component instantiations do not seem to appear in the generated documentation.

  3. The "Design Unit Hierarchy", which has in the past provided an extremely valuable aid to understanding the structure of a design and for navigating the documentation appears to have disappeared.

A very simple example is attached with Windows CHM files generated under both v1.7.5.1 and v1.7.6.1.

Doxygen is a very useful tool and I look forward to the above issues being resolved so that we can continue to benefit from other updates to the tool.

On 2012-01-11 17:55:10 +0000, mk wrote:

Created attachment 205035
bug fix for sequential comments

On 2012-01-11 17:55:43 +0000, mk wrote:

  1. fixed a bug

please separate \file and \class description with a blank line or
in this example with --!

--! \file test_component_rtl.vhdl
--! \brief Implementation of the test_component component.
--!
--! \class test_component
--! \brief Simple test component Napolean
--! \details Detailed description of test component.
--! \author Foo Bar
--!

see http://old.nabble.com/%5Cproperty-for-vhdl-td30662705.html

  1. In your example file test_component_rtl.vhdl


    --! Low pass filter

    U_FILTER : lowpass_filter

    Entity lowpass_filter does not exits, so it does't appear in the documentation.
    Create a dummy entity lowpass_filter and the component instatiation should appear in the doc.

  2. Architectures are removed from the Design Unit Hierarchy!
    In Xilinx (ISE) or Altera(Quartus) only entities occure in the hierarchy.

other options:

"SHOW_INCLUDE_FILES=NO"
all use clauses and libraries will not be shown.

"SHOW_INCLUDE_FILES=YES" and "FORCE_LOCAL_INCLUDES = yes"
only the standard IEEE use clauses (ieee.std_logic_1164,std.textio ..) will not be shown

default settings : "SHOW_INCLUDE_FILES=YES"
"FORCE_LOCAL_INCLUDES = NO"


one user constraint file can be added (.ucf from XILINX) or (.qsf from ALTERA)
a button "Constraints" will appear when you press button "DESING UNIT LISTS".

setting in config file:
FILE_PATTERNS = *.vhd *.vhdl *.qsf *.ucf

a comment start with #!

#! The PERIOD spec. covers all timing paths that start or end at a
#! register, latch, or synchronous RAM which are clocked by the reference
#! net (excluding pad destinations).

NET clock PERIOD = 50ns ;

when you include the attached patch

every vhdl code fragment, in particular sequential statements can be documented with the following command:

--! \brief decoding read/write:
--! \code decoding
rd<= '1' WHEN (cpu_read_n = '0') AND (cpu_be_n = '0') ELSE '0';
wr<= '1' WHEN (cpu_write_n = '0') AND (cpu_be_n = '0') ELSE '0';
--! \endcode

support VHDL-2008

To do: better support for configuration

On 2012-01-11 18:19:47 +0000, mk wrote:

My comment relates to the current svn version Doxygen-1.7.6.1-20120110.
Checkout and compile the current svn trunk.

A tip

entity comment
\class entity_name

architecture comment
\class architecture_name::entity_name

\class testcomponent::rtl

package body comment
\class _package name

package body MATH_REAL is

\class _MATH_REAL

On 2012-02-28 21:49:51 +0000, Tim James wrote:

(In reply to comment # 2)

  1. fixed a bug

please separate \file and \class description with a blank line or
in this example with --!

--! \file test_component_rtl.vhdl
--! \brief Implementation of the test_component component.
--!
--! \class test_component
--! \brief Simple test component Napolean
--! \details Detailed description of test component.
--! \author Foo Bar
--!

see http://old.nabble.com/%5Cproperty-for-vhdl-td30662705.html

The suggested work around fixes the problem with the entity not being documented. However it appears that documentation stops on any blank line. Therefore

--! \class test_component
--! \ingroup my_library
--! \brief One line description
--!
--! Paragraph with more detailed description.
--!
--! Another paragraph continuing detailed description.
--!

Correctly adds a brief description to the test_component architecture and associates it with the my_library group. However the detailed description text is lost (adding \details doesn't help either). This problem appears in v1.8.0.0. Is this expected?

On 2012-02-28 22:04:31 +0000, Tim James wrote:

(In reply to comment # 3)

My comment relates to the current svn version Doxygen-1.7.6.1-20120110.
Checkout and compile the current svn trunk.

A tip

entity comment
\class entity_name

architecture comment
\class architecture_name::entity_name

\class testcomponent::rtl

package body comment
\class _package name

package body MATH_REAL is

\class _MATH_REAL

This summary is very useful, thanks. What about package headers? Do I use \class package_name (this doesn't seem to work)? It would also be useful if it were possible to be able to remotely document objects (especially constants) that are declared in a package header. Can this be done?

Related to this, we use \ingroup keywords to group files into VHDL libraries. When used to associate package headers with a 'library' (resorting to putting all doxygen comments immediately prior to the declaration) the package appears to get listed in the group but the hyperlink is missing. (The package does appear, with hyperlink, on the 'packages' page.) Do I need to do something differently?

Thanks in advance.

Tim

On 2012-03-04 10:48:07 +0000, mk wrote:

(In reply to comment # 4)

(In reply to comment # 2)

  1. fixed a bug

please separate \file and \class description with a blank line or
in this example with --!

--! \file test_component_rtl.vhdl
--! \brief Implementation of the test_component component.
--!
--! \class test_component
--! \brief Simple test component Napolean
--! \details Detailed description of test component.
--! \author Foo Bar
--!

see http://old.nabble.com/%5Cproperty-for-vhdl-td30662705.html

The suggested work around fixes the problem with the entity not being
documented. However it appears that documentation stops on any blank line.
Therefore

--! \class test_component
--! \ingroup my_library
--! \brief One line description
--!
--! Paragraph with more detailed description.
--!
--! Another paragraph continuing detailed description.
--!

Correctly adds a brief description to the test_component architecture and
associates it with the my_library group. However the detailed description text
is lost (adding \details doesn't help either). This problem appears in
v1.8.0.0. Is this expected?

Only the first brief description appears in the group section, but the detailed and further descriptions appear
in entity reference of the test_component.

On 2012-03-04 10:54:11 +0000, mk wrote:

(In reply to comment # 5)

(In reply to comment # 3)

My comment relates to the current svn version Doxygen-1.7.6.1-20120110.
Checkout and compile the current svn trunk.

A tip

entity comment
\class entity_name

architecture comment
\class architecture_name::entity_name

\class testcomponent::rtl

package body comment
\class _package name

package body MATH_REAL is

\class _MATH_REAL

This summary is very useful, thanks. What about package headers? Do I use
\class package_name (this doesn't seem to work)? It would also be useful if it
were possible to be able to remotely document objects (especially constants)
that are declared in a package header. Can this be done?

Related to this, we use \ingroup keywords to group files into VHDL libraries.
When used to associate package headers with a 'library' (resorting to putting
all doxygen comments immediately prior to the declaration) the package appears
to get listed in the group but the hyperlink is missing. (The package does
appear, with hyperlink, on the 'packages' page.) Do I need to do something
differently?

Thanks in advance.

Tim

\class package_name works

You must set EXTRACT_PACKAGE = yes

Yes it is possible to remotly document objects.
I will send Dimitri a patch.

Can you post a small example for your last question ?

On 2012-03-05 09:31:01 +0000, Tim James wrote:

Created attachment 208981
Example to illustrate VHDL problems

In reply to comment # 6 and comment # 7.
Hopefully the attached example will help illustrate my problems (or at least help you figure out what I'm doing wrong).

This project contains two libraries, my_design_lib and my_project_lib, which contain a couple of packages and a couple of components.

With EXTRACT_PACKAGE set to its default value (false), the two packages are
listed on the Packages page. However, they do not appear hyperlinked under
Modules -> VHDL Libraries -> my_design_lib. (Setting EXTRACT_PACKAGE to true
does appear to fix this problem (although this behaviour is not very intuitive).)

In all cases, eg, detailed description of addressable_shift_register, example_design and design_components_pkg, the detailed description text appears to have been lost. Moreover, in the case of the package headers, the tool appears to have incorrectly taken the brief for the first item inside the package header as the brief for the package header itself. (This then causes a warning to be generated stating that the first item is not documented!)

Incidentally, the process and component instantiation inside example_design do not appear to have been documented either. Presumably this is why there is no design hierarchy shown?

Thanks for you help.

Tim

On 2012-03-06 20:18:38 +0000, mk wrote:

(In reply to comment # 8)

Created an attachment (id=208981) [details]
Example to illustrate VHDL problems

In reply to comment # 6 and comment # 7.
Hopefully the attached example will help illustrate my problems (or at least
help you figure out what I'm doing wrong).

This project contains two libraries, my_design_lib and my_project_lib, which
contain a couple of packages and a couple of components.

With EXTRACT_PACKAGE set to its default value (false), the two packages are
listed on the Packages page. However, they do not appear hyperlinked under
Modules -> VHDL Libraries -> my_design_lib. (Setting EXTRACT_PACKAGE to true
does appear to fix this problem (although this behaviour is not very
intuitive).)

In all cases, eg, detailed description of addressable_shift_register,
example_design and design_components_pkg, the detailed description text appears
to have been lost. Moreover, in the case of the package headers, the tool
appears to have incorrectly taken the brief for the first item inside the
package header as the brief for the package header itself. (This then causes a
warning to be generated stating that the first item is not documented!)

Incidentally, the process and component instantiation inside example_design do
not appear to have been documented either. Presumably this is why there is no
design hierarchy shown?

Thanks for you help.

Tim

      -- Width of the data ports
        NBITS_DATA              => DATA_IN'length -- ',

        -- Depth of the shift register, 5 -> 32, 6 -> 64
        LOG2_DEPTH              => DATA_OUT_ADDR'length -- '

A comma is missing after DATA_IN'length ( Syntax error)
NBITS_DATA => DATA_IN'length,

should fix the process and component_instantiation issue.

--! \file example_design_rtl.vhdl
--! \brief Implementation of the example_design component.
--!
--! \class example_design
--! \ingroup my_project_lib
--! \brief Example design.
--!
--! Detailed description.
--!
--! Additional information.
--!

A workaround for the description issue.
Please make a space after --!
When ('\n') exists after --!, the scanner starts a new comment section.
Copy and Paste this comment and parse it.

On 2012-03-10 16:49:18 +0000, Dimitri van Heesch wrote:

Martin send me a patch which should solve the problem. I'll include it in the next update.

On 2012-05-19 12:27:01 +0000, Dimitri van Heesch wrote:

This bug was previously marked ASSIGNED, which means it should be fixed in
doxygen version 1.8.1. Please verify if this is indeed the case. Reopen the
bug if you think it is not fixed and please include any additional information
that you think can be relevant.

@doxygen doxygen closed this Jul 2, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment