CODEWITHSUNDEEP
vhdldoxygen
Daniel J. Greenhoe
Daniel J. Greenhoe

Reputation: 163

Is it possible to use \code in doxygen 1.8.14 in VHDL descriptions?

For C++ code, doxygen has no insurmountable problem with \code{.markdown}. For example

//===========================================================================
//! \defgroup markdown_cpp C++ markdown test
//! \brief         test cpp markdown
//! \date          2018 March
//!
//! \code{.markdown}
//!         ______ 
//!        |      |
//!   x ->-|      |->- y
//!        |______|
//! \endcode
//===========================================================================
int test(void)
  {
  const unsigned x=3;
  return x*2;
  }

and it produces in a .tex file 

\begin{DoxyCode}
      \_\_\_\_\_\_ 
     |      |
x ->-|      |->- y
     |\_\_\_\_\_\_|
\end{DoxyCode}

However, in VHDL code, doxygen crashes on Windows 10 ("doxygen.exe has stopped working") when I attempt this:

library IEEE;
use IEEE.STD_LOGIC_1164.all;
-----------------------------------------------------------------------------
--! \defgroup markdown_vhd VHDL markdown test
--! \ingroup  markdown_vhd
--!
--! \code{.markdown}
--!            ______ 
--!           |      |
--!     x1 ->-|      |
--!           |      |->- y
--!     x2 ->-|      |
--!           |______|
--! \endcode
-----------------------------------------------------------------------------
entity test is
  port (--inpts
         x1 : in  std_logic;
         x2 : in  std_logic;
        --outputs
          y : out std_logic;
        );
end entity test;

architecture test_arch of test is
begin
  y <= x1 xor x2;
end architecture test_arch;

Upvotes: 2

Views: 691

Answers (2)

M24
M24

Reputation: 109

The syntax for your doxygen comment in your example is correct. This is resulting in a crash which is a bug (tested in doxygen 1.8.11 in windows).

All commands in the documentation start with a backslash (\) or an at-sign (@), see doxygen manual. To achieve the exact same (intended) result, use the following:

--! @code{.markdown}
--!            ______ 
--!           |      |
--!     x1 ->-|      |
--!           |      |->- y
--!     x2 ->-|      |
--!           |______|
--! @endcode

It will not crash in doxygen (tested in 1.8.11 on windows).

produced html result for code: produced html result for code

You may also be interested in the following variant:

--! \verbatim
--!            ______ 
--!           |      |
--!     x1 ->-|      |
--!           |      |->- y
--!     x2 ->-|      |
--!           |______|
--! \endverbatim

The outcome is different:

produced html result for verbatim: produced html result for verbatim

Note 1: I do not have the latest version installed on my machine which is why I used an slightly older version. It will hopefully not affect the provided solution.

Note 2: Workaround had been successfully tested for 1.8.14 by OP.

Upvotes: 1

Daniel J. Greenhoe
Daniel J. Greenhoe

Reputation: 163

All of the following work for Doxygen 1.8.14 on Windows 10:

--!
--! @code{.markdown}
--!            ______ 
--!           |      |
--!     x1 ->-|      |
--!           |      |->- y
--!     x2 ->-|      |
--!           |______|
--! @endcode
--!
--! \verbatim
--!            ______ 
--!           |      |
--!     x1 ->-|      |
--!           |      |->- y
--!     x2 ->-|      |
--!           |______|
--! \endverbatim
--!
--! @verbatim
--!            ______ 
--!           |      |
--!     x1 ->-|      |
--!           |      |->- y
--!     x2 ->-|      |
--!           |______|
--! @endverbatim

These produce the following LaTeX code:

\begin{DoxyCode}
       \_\_\_\_\_\_ 
      |      |
x1 ->-|      |
      |      |->- y
x2 ->-|      |
      |\_\_\_\_\_\_|
\end{DoxyCode}


\begin{DoxyVerb}            ______ 
           |      |
     x1 ->-|      |
           |      |->- y
     x2 ->-|      |
           |______|\end{DoxyVerb}


\begin{DoxyVerb}            ______ 
           |      |
     x1 ->-|      |
           |      |->- y
     x2 ->-|      |
           |______|\end{DoxyVerb}

The --! leads are completely stripped out with @code, replaced with spaces (plus an additional space) with the \verbatim and @verbatim. The DoxyCode environment is defined as

\newenvironment{DoxyCode}{%
  \par%
  \scriptsize%
  \begin{alltt}%
}{%
  \end{alltt}%
  \normalsize%
}

where alltt is defined in the alltt package: https://ctan.org/pkg/alltt and the DoxyVerb is defined as 

\newenvironment{DoxyVerb}{%
  \footnotesize%
  \verbatim%
}{%
  \endverbatim%
  \normalsize%
}

Note that the verbatim methods typeset larger ("\footnotesize") than the @code ("\scriptsize").

Many many thanks to @M24 for very helpful help.

Upvotes: 0

Related Questions