12

I have a source repository in C++ (and some CUDA), which I want to doxygenate. I've added doxygen comments to some - but not all - of the code; generated a Doxygen config file, and ran doxygen with it to see some partial output.

What I get is: Nothing. Empty.

A main page is generated, it just doesn't show anything - even though I specifically set EXTRACT_ALL = YES (after getting empty results with EXTRACT_ALL = NO.

Why is nothing being generated and how can I fix it?

Notes:

  • All header files have @file comments.
  • I've added CUDA-related extensions to the allowed patterns
  • I had an earlier version of this question, with no answers following which the situation changed somewhat (so I deleted that one).
  • Even when removing most lines out of the doxygen.cfg (see below), the problem persists.


doxygen.cfg (shorter version, with comments filtered out):

DOXYFILE_ENCODING = UTF-8 PROJECT_NAME = "cuda-api-wrappers" PROJECT_BRIEF = "Thin C++-flavored wrappers for the CUDA Runtime API" OUTPUT_DIRECTORY = docs ALLOW_UNICODE_NAMES = YES OUTPUT_LANGUAGE = English BRIEF_MEMBER_DESC = YES REPEAT_BRIEF = YES FULL_PATH_NAMES = YES JAVADOC_AUTOBRIEF = YES QT_AUTOBRIEF = NO MULTILINE_CPP_IS_BRIEF = NO INHERIT_DOCS = YES SEPARATE_MEMBER_PAGES = NO TAB_SIZE = 4 EXTENSION_MAPPING = cu=C++ cuh=C++ cuhpp=C++ hpp=C++ MARKDOWN_SUPPORT = YES AUTOLINK_SUPPORT = YES BUILTIN_STL_SUPPORT = YES SUBGROUPING = YES LOOKUP_CACHE_SIZE = 2 EXTRACT_ALL = YES EXTRACT_LOCAL_CLASSES = YES HIDE_UNDOC_MEMBERS = NO HIDE_UNDOC_CLASSES = NO HIDE_FRIEND_COMPOUNDS = NO CASE_SENSE_NAMES = YES HIDE_SCOPE_NAMES = NO HIDE_COMPOUND_REFERENCE= NO SHOW_INCLUDE_FILES = YES SHOW_GROUPED_MEMB_INC = NO FORCE_LOCAL_INCLUDES = NO INLINE_INFO = YES SORT_MEMBER_DOCS = YES STRICT_PROTO_MATCHING = NO MAX_INITIALIZER_LINES = 30 SHOW_USED_FILES = YES SHOW_FILES = YES SHOW_NAMESPACES = YES QUIET = NO WARNINGS = YES WARN_IF_UNDOCUMENTED = YES WARN_IF_DOC_ERROR = YES WARN_NO_PARAMDOC = NO WARN_AS_ERROR = NO WARN_FORMAT = "$file:$line: $text" INPUT = src INPUT_ENCODING = UTF-8 FILE_PATTERNS = *.c, *.cc, *.cxx, *.cpp, *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, *.hh, *.hxx, *.hpp, *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc, *.m, *.markdown, *.md, *.mm, *.dox, *.py, *.pyw, *.f90, *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf, *.qsf, *.as *.js, *.cuh, *.cu, *.cuhpp RECURSIVE = YES

Doxygen console output:

Adding custom extension mapping: .cu will be treated as language c++ Adding custom extension mapping: .cuh will be treated as language c++ Adding custom extension mapping: .cuhpp will be treated as language c++ Adding custom extension mapping: .hpp will be treated as language c++ Searching for include files... Searching for example files... Searching for images... Searching for dot files... Searching for msc files... Searching for dia files... Searching for files to exclude Searching INPUT for files to process... Searching for files in directory /home/eyalroz/src/mine/cuda-api-wrappers/src Searching for files in directory /home/eyalroz/src/mine/cuda-api-wrappers/src/cuda Searching for files in directory /home/eyalroz/src/mine/cuda-api-wrappers/src/cuda/api Reading and parsing tag files Parsing files Building group list... Building directory list... Building namespace list... Building file list... Building class list... Associating documentation with classes... Computing nesting relations for classes... Building example list... Searching for enumerations... Searching for documented typedefs... Searching for members imported via using declarations... Searching for included using directives... Searching for documented variables... Building interface member list... Building member list... Searching for friends... Searching for documented defines... Computing class inheritance relations... Computing class usage relations... Flushing cached template relations that have become invalid... Creating members for template instances... Computing class relations... Add enum values to enums... Searching for member function documentation... Building page list... Search for main page... Computing page relations... Determining the scope of groups... Sorting lists... Freeing entry tree Determining which enums are documented Computing member relations... Building full member lists recursively... Adding members to member groups. Computing member references... Inheriting documentation... Generating disk names... Adding source references... Adding xrefitems... Sorting member lists... Computing dependencies between directories... Generating citations page... Counting data structures... Resolving user defined references... Finding anchors and sections in the documentation... Transferring function references... Combining using relations... Adding members to index pages... Generating style sheet... Generating search indices... Generating example documentation... Generating file sources... Generating file documentation... Generating page documentation... Generating group documentation... Generating class documentation... Generating namespace index... Generating graph info page... Generating directory documentation... Generating index page... Generating page index... Generating module index... Generating namespace index... Generating namespace member index... Generating annotated compound index... Generating alphabetical compound index... Generating hierarchical class index... Generating graphical class hierarchy... Generating member index... Generating file index... Generating file member index... Generating example index... finalizing index lists... writing tag file... Running dot... lookup cache used 127/262144 hits=628 misses=194 finished...
Improve this question
12
  • 2
    Post your used Doxyfile (doxygen.cfg) as it looks like it is not correct, a link is no god (might vanish in the, near, future). Commented Mar 29, 2017 at 13:38
  • 2
    This is a "why isn't this code working" question. Those questions are supposed to have a minimal reproducible example in the question itself. Commented Mar 29, 2017 at 13:50
  • 2
    Looks like the FILE_PATTERN should not have the commas (,) in it, it is a space delimited list, now the comma is added to the file extension. Commented Mar 29, 2017 at 16:14
  • 1
    @albert: That's it! awesome!... if you want, feel free to post that as an answer and I'll accept. Commented Mar 29, 2017 at 16:36
  • 1
    I recently pushed a proposed patch to doxygen github (pull request 6563, github.com/doxygen/doxygen/pull/6563) and this has been integrated in master. The pull request was to enable commas in lists. Commented Oct 23, 2018 at 8:30

1 Answer 1

Reset to default
9

TL;DR: Drop the commas in the FILE_PATTERNS variable and make it space-separated.

Instead of:

FILE_PATTERNS = *.c, *.cc, *.cxx, *.etc

you should use:

FILE_PATTERNS = *.c *.cc *.cxx *.etc

Explanation

@albert is the one who cracked this conundrum...

The Doxygen-generated config file says:

# If the value of the INPUT tag contains directories, you can use the # FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp and # *.h) to filter out the source-files in the directories. # # Note that for custom extensions or not directly supported extensions you also # need to set EXTENSION_MAPPING for the extension otherwise the files are not # read by doxygen. # # If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp, # *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, # *.hh, *.hxx, *.hpp, *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc, # *.m, *.markdown, *.md, *.mm, *.dox, *.py, *.pyw, *.f90, *.f, *.for, *.tcl, # *.vhd, *.vhdl, *.ucf, *.qsf, *.as and *.js. FILE_PATTERNS =

this comment is misleading, since it gives you a comma-separated list, while in fact commas are not treated as separators. If you use that list (and perhaps add/change it), like in OP's example, Doxygen sees a list of patterns with the extensions having a trailing , character. And - it doesn't complain. It also doesn't complain about ignoring essentially all files in the repository - it just ends up with an empty result.

Dropping the , characters results in non-empty generated documentation.

Note: Beginning with Doxygen version 1.8.15, this should no longer be an issue, and commas should be accepted as delimiters of fields.

Improve this answer
Sign up to request clarification or add additional context in comments.

5 Comments

I recently pushed a proposed patch to doxygen github (pull request 6563, github.com/doxygen/doxygen/pull/6563) and this has been integrated in master. The pull request was to enable commas in lists.
@albert: Can you tell us which doxygen release is the first to have your patch integrated?
From the date of the releases compared to the date of the integration this gives version 1.8.15. When looking at the changelog (doxygen.nl/manual/changelog.html) and searching for the text of the pull request "Enable comma as separator in configuration lists" this also gives 1.8.15
@albert WOW! It's 2021 and sudo apt-get install doxygen on Ubuntu 16.04 gives me Doxygen version 1.8.11 !! Then sudo apt-get update followed by repeating sudo apt-get install doxygen leads to doxygen is already the newest version (1.8.11-1ubuntu0.1).. Now that I see your revision history though, the 1.8.15 seems to have been added to your answer only in 2020, so it's not that bad.
@user1271772: You do realize that Ubuntu 16.04 contains software from 2016, and probably a lot of it is from late 2015, right? ... and that will continue to be the case in 2022, 2023 and forever :-P

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.