[Doxygen-users] Some VHDL questions

[Viktor P. <pu...@ce...>]

Hi all,

I`m trying to use Doxygen to document the VHDL code, but I`m quite new to it (Doxygen, not VHDL). I have two questions:

Q1:
How exactly does the automatic brief/details division work? The example at http://www.stack.nl/~dimitri/doxygen/docblocks.html#vhdlblocks documents the entity by
--! Mux entity brief description
--! Detailed description of this 
--! mux design element.

But the corresponding generated documentation at http://www.stack.nl/~dimitri/doxygen/examples/mux/html/classmux__using__with.html shows the sentence "Detailed description of this mux design element." incorrectly at the description of din_0 in std_logic. Explicitly saying \brief and \details works OK, but the implicit way would be less intrusive.

Q2:
Can Doxygen document the hierarchy of instances? I`m talking about the situation when a module includes (instantiates) a submodule and so on. This is very common in VHDL, and IMHO a true killer-feature of each VHDL documentation system. Unlike many other languages, this is static, and therefore can be analyzed at the compile time. 
It seems to me that there is some bug in this, because any processes that appear in the code after the submodule instantion are not documented by Doxygen. Here is the minimal example:

--! Toplevel entity
entity top is
  port(
     input : in std_logic;
     output : out std_logic;
  );
end top;
--! Architecture of toplevel entity
architecture behav of top is
begin
  --! Documented process
  process_1 : process(input)
  begin
  end;
  --! Undocumented submodule instance
  instance_1 : entity work.submodule
  port map(
     i => input,
     o => output
  )
  --! Undocumented process
  process_2 : process(input)
  begin
  end;
end architecture behav;

I'll be glad for any advices/comments from someone who is using Doxygen to document VHDL.

Best regards,
Viktor