LaTeX output does not get generated

j-marjanovic commented 8 years ago

There is a bug which halts generation of LaTeX output when the project is composed of multiple Verilog modules.

Follows a minimal example which enables replication of this bug. When the line input clk in simple_submodule.v is commented out, the LaTeX output is correctly generated and this is the contents of the latex directory:

➜  latex_bug git:(master) ✗ ls -l latex
total 64
-rw-rw-r-- 1 jan jan   445 avg 10 22:35 annotated.tex
-rw-rw-r-- 1 jan jan   358 avg 10 22:35 dir_b95d22fb74c8ef837e5dec850a739e17.tex
-rw-rw-r-- 1 jan jan 11788 avg 10 22:35 doxygen.sty
-rw-rw-r-- 1 jan jan  3796 avg 10 22:35 enumsimple__submodule.eps
-rw-rw-r-- 1 jan jan  4759 avg 10 22:35 enumsimple__submodule.pdf
-rw-rw-r-- 1 jan jan   645 avg 10 22:35 enumsimple__submodule.tex
-rw-rw-r-- 1 jan jan  3796 avg 10 22:35 enumtop__module.eps
-rw-rw-r-- 1 jan jan  4753 avg 10 22:35 enumtop__module.pdf
-rw-rw-r-- 1 jan jan  1377 avg 10 22:35 enumtop__module.tex
-rw-rw-r-- 1 jan jan   364 avg 10 22:35 hierarchy.tex
-rw-rw-r-- 1 jan jan   469 avg 10 22:35 Makefile
-rw-rw-r-- 1 jan jan  1803 avg 10 22:35 refman.tex

When the line input clk is present the refman.tex is missing:

➜  latex_bug git:(master) ✗ ls -l latex
total 48
-rw-rw-r-- 1 jan jan 11788 avg 10 22:36 doxygen.sty
-rw-rw-r-- 1 jan jan  3796 avg 10 22:36 enumsimple__submodule.eps
-rw-rw-r-- 1 jan jan  4759 avg 10 22:36 enumsimple__submodule.pdf
-rw-rw-r-- 1 jan jan  1006 avg 10 22:36 enumsimple__submodule.tex
-rw-rw-r-- 1 jan jan  3796 avg 10 22:36 enumtop__module.eps
-rw-rw-r-- 1 jan jan  4753 avg 10 22:36 enumtop__module.pdf
-rw-rw-r-- 1 jan jan  1153 avg 10 22:36 enumtop__module.tex
-rw-rw-r-- 1 jan jan   469 avg 10 22:36 Makefile

Files

top_module.v

//% @brief Top-Level Module
//% @date August 2016

module top_module (
    //% clock input
    input clk_in
);

//% simple submodule
simple_submodule simple_submodule_inst (
    .clk(clk_in)
);

endmodule

simple_submodule.v

//% @brief A simple submodule
//% @date August 2016

module simple_submodule (
    //% clock input
    input clk  // <- commenting out this line fixes LaTex gen issue
);

endmodule

verilog.cfg (Doxverilog configuration file)

# Doxyfile 1.8.1

#---------------------------------------------------------------------------
# Project related configuration options
#---------------------------------------------------------------------------
DOXYFILE_ENCODING      = UTF-8
PROJECT_NAME           = "My Project"
PROJECT_NUMBER         =
PROJECT_BRIEF          =
PROJECT_LOGO           =
OUTPUT_DIRECTORY       =
CREATE_SUBDIRS         = NO
OUTPUT_LANGUAGE        = English
BRIEF_MEMBER_DESC      = YES
REPEAT_BRIEF           = YES
ABBREVIATE_BRIEF       =
ALWAYS_DETAILED_SEC    = NO
INLINE_INHERITED_MEMB  = NO
FULL_PATH_NAMES        = YES
STRIP_FROM_PATH        =
STRIP_FROM_INC_PATH    =
SHORT_NAMES            = NO
JAVADOC_AUTOBRIEF      = NO
QT_AUTOBRIEF           = NO
MULTILINE_CPP_IS_BRIEF = NO
INHERIT_DOCS           = YES
SEPARATE_MEMBER_PAGES  = NO
TAB_SIZE               = 8
ALIASES                =
TCL_SUBST              =
OPTIMIZE_OUTPUT_FOR_C  = NO
OPTIMIZE_OUTPUT_JAVA   = NO
OPTIMIZE_FOR_FORTRAN   = NO
OPTIMIZE_OUTPUT_VHDL   = NO
OPTIMIZE_OUTPUT_VERILOG= YES
HIDE_PORT              = YES
EXTENSION_MAPPING      =
MARKDOWN_SUPPORT       = YES
BUILTIN_STL_SUPPORT    = NO
CPP_CLI_SUPPORT        = NO
SIP_SUPPORT            = NO
IDL_PROPERTY_SUPPORT   = YES
DISTRIBUTE_GROUP_DOC   = NO
SUBGROUPING            = YES
INLINE_GROUPED_CLASSES = NO
INLINE_SIMPLE_STRUCTS  = NO
TYPEDEF_HIDES_STRUCT   = NO
SYMBOL_CACHE_SIZE      = 0
LOOKUP_CACHE_SIZE      = 0
#---------------------------------------------------------------------------
# Build related configuration options
#---------------------------------------------------------------------------
EXTRACT_ALL            = NO
EXTRACT_PRIVATE        = NO
EXTRACT_PACKAGE        = NO
EXTRACT_STATIC         = NO
EXTRACT_LOCAL_CLASSES  = YES
EXTRACT_LOCAL_METHODS  = NO
EXTRACT_ANON_NSPACES   = NO
HIDE_UNDOC_MEMBERS     = NO
HIDE_UNDOC_CLASSES     = NO
HIDE_FRIEND_COMPOUNDS  = NO
HIDE_IN_BODY_DOCS      = NO
INTERNAL_DOCS          = NO
CASE_SENSE_NAMES       = YES
HIDE_SCOPE_NAMES       = NO
SHOW_INCLUDE_FILES     = YES
FORCE_LOCAL_INCLUDES   = NO
INLINE_INFO            = YES
SORT_MEMBER_DOCS       = YES
SORT_BRIEF_DOCS        = NO
SORT_MEMBERS_CTORS_1ST = NO
SORT_GROUP_NAMES       = NO
SORT_BY_SCOPE_NAME     = NO
STRICT_PROTO_MATCHING  = NO
GENERATE_TODOLIST      = YES
GENERATE_TESTLIST      = YES
GENERATE_BUGLIST       = YES
GENERATE_DEPRECATEDLIST= YES
ENABLED_SECTIONS       =
MAX_INITIALIZER_LINES  = 30
SHOW_USED_FILES        = YES
SHOW_FILES             = YES
SHOW_NAMESPACES        = YES
FILE_VERSION_FILTER    =
LAYOUT_FILE            =
CITE_BIB_FILES         =
#---------------------------------------------------------------------------
# configuration options related to warning and progress messages
#---------------------------------------------------------------------------
QUIET                  = NO
WARNINGS               = YES
WARN_IF_UNDOCUMENTED   = YES
WARN_IF_DOC_ERROR      = YES
WARN_NO_PARAMDOC       = NO
WARN_FORMAT            = "$file:$line: $text"
WARN_LOGFILE           =
#---------------------------------------------------------------------------
# configuration options related to the input files
#---------------------------------------------------------------------------
INPUT                  = simple_submodule.v top_module.v

INPUT_ENCODING         = UTF-8
FILE_PATTERNS          =
RECURSIVE              = NO
EXCLUDE                =
EXCLUDE_SYMLINKS       = NO
EXCLUDE_PATTERNS       =
EXCLUDE_SYMBOLS        =
EXAMPLE_PATH           =
EXAMPLE_PATTERNS       =
EXAMPLE_RECURSIVE      = NO
IMAGE_PATH             =
INPUT_FILTER           =
FILTER_PATTERNS        =
FILTER_SOURCE_FILES    = NO
FILTER_SOURCE_PATTERNS =
#---------------------------------------------------------------------------
# configuration options related to source browsing
#---------------------------------------------------------------------------
SOURCE_BROWSER         = NO
INLINE_SOURCES         = NO
STRIP_CODE_COMMENTS    = YES
REFERENCED_BY_RELATION = NO
REFERENCES_RELATION    = NO
REFERENCES_LINK_SOURCE = YES
USE_HTAGS              = NO
VERBATIM_HEADERS       = YES
#---------------------------------------------------------------------------
# configuration options related to the alphabetical class index
#---------------------------------------------------------------------------
ALPHABETICAL_INDEX     = YES
COLS_IN_ALPHA_INDEX    = 5
IGNORE_PREFIX          =
#---------------------------------------------------------------------------
# configuration options related to the HTML output
#---------------------------------------------------------------------------
GENERATE_HTML          = YES
HTML_OUTPUT            = html
HTML_FILE_EXTENSION    = .html
HTML_HEADER            =
HTML_FOOTER            =
HTML_STYLESHEET        =
HTML_EXTRA_FILES       =
HTML_COLORSTYLE_HUE    = 220
HTML_COLORSTYLE_SAT    = 100
HTML_COLORSTYLE_GAMMA  = 80
HTML_TIMESTAMP         = YES
HTML_DYNAMIC_SECTIONS  = NO
HTML_INDEX_NUM_ENTRIES = 100
GENERATE_DOCSET        = NO
DOCSET_FEEDNAME        = "Doxygen generated docs"
DOCSET_BUNDLE_ID       = org.doxygen.Project
DOCSET_PUBLISHER_ID    = org.doxygen.Publisher
DOCSET_PUBLISHER_NAME  = Publisher
GENERATE_HTMLHELP      = NO
CHM_FILE               =
HHC_LOCATION           =
GENERATE_CHI           = NO
CHM_INDEX_ENCODING     =
BINARY_TOC             = NO
TOC_EXPAND             = NO
GENERATE_QHP           = NO
QCH_FILE               =
QHP_NAMESPACE          = org.doxygen.Project
QHP_VIRTUAL_FOLDER     = doc
QHP_CUST_FILTER_NAME   =
QHP_CUST_FILTER_ATTRS  =
QHP_SECT_FILTER_ATTRS  =
QHG_LOCATION           =
GENERATE_ECLIPSEHELP   = NO
ECLIPSE_DOC_ID         = org.doxygen.Project
DISABLE_INDEX          = NO
GENERATE_TREEVIEW      = NO
ENUM_VALUES_PER_LINE   = 4
TREEVIEW_WIDTH         = 250
EXT_LINKS_IN_WINDOW    = NO
FORMULA_FONTSIZE       = 10
FORMULA_TRANSPARENT    = YES
USE_MATHJAX            = NO
MATHJAX_RELPATH        = http://cdn.mathjax.org/mathjax/latest
MATHJAX_EXTENSIONS     =
SEARCHENGINE           = YES
SERVER_BASED_SEARCH    = NO
#---------------------------------------------------------------------------
# configuration options related to the LaTeX output
#---------------------------------------------------------------------------
GENERATE_LATEX         = YES
LATEX_OUTPUT           = latex
LATEX_CMD_NAME         = latex
MAKEINDEX_CMD_NAME     = makeindex
COMPACT_LATEX          = NO
PAPER_TYPE             = a4
EXTRA_PACKAGES         =
LATEX_HEADER           =
LATEX_FOOTER           =
PDF_HYPERLINKS         = YES
USE_PDFLATEX           = YES
LATEX_BATCHMODE        = NO
LATEX_HIDE_INDICES     = NO
LATEX_SOURCE_CODE      = NO
LATEX_BIB_STYLE        = plain
#---------------------------------------------------------------------------
# configuration options related to the RTF output
#---------------------------------------------------------------------------
GENERATE_RTF           = NO
RTF_OUTPUT             = rtf
COMPACT_RTF            = NO
RTF_HYPERLINKS         = NO
RTF_STYLESHEET_FILE    =
RTF_EXTENSIONS_FILE    =
#---------------------------------------------------------------------------
# configuration options related to the man page output
#---------------------------------------------------------------------------
GENERATE_MAN           = NO
MAN_OUTPUT             = man
MAN_EXTENSION          = .3
MAN_LINKS              = NO
#---------------------------------------------------------------------------
# configuration options related to the XML output
#---------------------------------------------------------------------------
GENERATE_XML           = NO
XML_OUTPUT             = xml
XML_SCHEMA             =
XML_DTD                =
XML_PROGRAMLISTING     = YES
#---------------------------------------------------------------------------
# configuration options for the AutoGen Definitions output
#---------------------------------------------------------------------------
GENERATE_AUTOGEN_DEF   = NO
#---------------------------------------------------------------------------
# configuration options related to the Perl module output
#---------------------------------------------------------------------------
GENERATE_PERLMOD       = NO
PERLMOD_LATEX          = NO
PERLMOD_PRETTY         = YES
PERLMOD_MAKEVAR_PREFIX =
#---------------------------------------------------------------------------
# Configuration options related to the preprocessor
#---------------------------------------------------------------------------
ENABLE_PREPROCESSING   = YES
MACRO_EXPANSION        = NO
EXPAND_ONLY_PREDEF     = NO
SEARCH_INCLUDES        = YES
INCLUDE_PATH           =
INCLUDE_FILE_PATTERNS  =
PREDEFINED             =
EXPAND_AS_DEFINED      =
SKIP_FUNCTION_MACROS   = YES
#---------------------------------------------------------------------------
# Configuration::additions related to external references
#---------------------------------------------------------------------------
TAGFILES               =
GENERATE_TAGFILE       =
ALLEXTERNALS           = NO
EXTERNAL_GROUPS        = YES
PERL_PATH              = /usr/bin/perl
#---------------------------------------------------------------------------
# Configuration options related to the dot tool
#---------------------------------------------------------------------------
CLASS_DIAGRAMS         = YES
MSCGEN_PATH            =
HIDE_UNDOC_RELATIONS   = YES
HAVE_DOT               = NO
DOT_NUM_THREADS        = 0
DOT_FONTNAME           = Helvetica
DOT_FONTSIZE           = 10
DOT_FONTPATH           =
CLASS_GRAPH            = YES
COLLABORATION_GRAPH    = YES
GROUP_GRAPHS           = YES
UML_LOOK               = NO
UML_LIMIT_NUM_FIELDS   = 10
TEMPLATE_RELATIONS     = NO
INCLUDE_GRAPH          = YES
INCLUDED_BY_GRAPH      = YES
CALL_GRAPH             = NO
CALLER_GRAPH           = NO
GRAPHICAL_HIERARCHY    = YES
DIRECTORY_GRAPH        = YES
DOT_IMAGE_FORMAT       = png
INTERACTIVE_SVG        = NO
DOT_PATH               =
DOTFILE_DIRS           =
MSCFILE_DIRS           =
DOT_GRAPH_MAX_NODES    = 50
MAX_DOT_GRAPH_DEPTH    = 0
DOT_TRANSPARENT        = NO
DOT_MULTI_TARGETS      = NO
GENERATE_LEGEND        = YES
DOT_CLEANUP            = YES

j-marjanovic commented 8 years ago

From what I found out so far, there is a problem in Generating class documentation... phase. When the offending line is present an assertion fails when the documentation for top_module is being generated:

Generating class documentation...
Generating docs for compound simple_submodule...
[debug]: virtual void LatexGenerator::startFile(const char*, const char*, const char*), name: enumsimple__submodule
Generating docs for compound top_module...
[debug]: virtual void LatexGenerator::startFile(const char*, const char*, const char*), name: enumtop__module
ASSERT: "m_numDecMembers!=-1" in memberlist.h (134)
Generating namespace index...
Generating graph info page...
Generating directory documentation...

Ductapemaster commented 8 years ago

Jan,

Thanks for all the documentation. A couple quick ideas:

Have you tried putting the doxygen comment for the signal after the signal name? Such as:

//% @brief A simple submodule
//% @date August 2016

module simple_submodule (
    input clk  //% clock input
);

endmodule

Does the same behavior occur if you have two signals? I have found that certain items act odd when acting upon or involving the last item in a port list (in VHDL at least). For example if you have a group:

entity Test is
port (

    --! @name External Clock Inputs
    --! @{
    signal clk_50mhz         : in    std_logic;                        --! Main system clock

    --! @}

    --! @name UARTs and Generic IO
    --! @{
    signal uat_txd            : out   std_logic;
    signal uar_rxd            : in    std_logic;
    signal fpga_io            : inout std_logic_vector(7 downto 0)

);

-- Doxygen needs this group to be after the semicolon, otherwise the last signal in the port list is not picked up.
--! @}
end entity Test;

Sorry, I know that example is in VHDL, but that's what I happen to be writing in at the moment...the same idea should apply to Verilog though, since they use pretty much the same parsing elements.

j-marjanovic commented 8 years ago

Unfortunately neither moving the doxygen comment after the signal name neither adding more signals does not resolve this issue.

I did however managed to generate LaTeX output by forcing INLINE_INHERITED_MEMB configuration option to true in endMemberDeclarations function:

void ClassDef::endMemberDeclarations(OutputList &ol)
{
  //printf("%s: ClassDef::endMemberDeclarations()\n",name().data());
  static bool inlineInheritedMembers = Config_getBool("INLINE_INHERITED_MEMB");
  inlineInheritedMembers = true;
  printf("[debug] %s, inlineInheritedMembers: %s\n", __PRETTY_FUNCTION__, inlineInheritedMembers ? "true" : "false");
  if (!inlineInheritedMembers && countAdditionalInheritedMembers()>0)
  ...

Does it have any sense to have INLINE_INHERITED_MEMB enabled for VHDL and (non-System) Verilog? I would assume that this option only makes sense for OO languages.

Ductapemaster / doxverilog