GNOME Bugzilla – Bug 666088
Significant loss of functionality in v1.7.6.1 for VHDL builds
Last modified: 2012-05-19 12:27:01 UTC
Created attachment 203342 [details] 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.
Created attachment 205035 [details] [review] bug fix for sequential comments
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 2) 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. 3) 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
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
(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?
(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
(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.
(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 ?
Created attachment 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
(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.
Martin send me a patch which should solve the problem. I'll include it in the next update.
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.