    ___              _ _ ____
   /   |  __________(_|_) __ \____  _  ____  __
  / /| | / ___/ ___/ / / / / / __ \| |/_/ / / /
 / ___ |(__  ) /__/ / / /_/ / /_/ />  </ /_/ /
/_/  |_/____/\___/_/_/_____/\____/_/|_|\__, /
                                      /____/

Doxygen

For extracting documentation from source code, AsciiDoxy relies on Doxygen. You are expected to run Doxygen on your source code, and then provide the path to the generated XML files to AsciiDoxy. It is recommended to set at least the following non-default settings in your Doxyfile when generating the XML.

C++

GENERATE_XML           = YES

Java

GENERATE_XML           = YES
JAVADOC_AUTOBRIEF      = YES
OPTIMIZE_OUTPUT_JAVA   = YES

Doxygen does not support all kinds of annotations. For example the annotations of return types are removed. To trick Doxygen into passing annotations to AsciiDoxy, you need to transform them into a name that does not contain @. AsciiDoxy supports changing type prefixes like __AT__Annotation__ back into @Annotation. For example to pass through all annotations with information about nullability, add the following to the Doxygen file:

FILTER_PATTERNS        = *.java="sed -E 's/@(Nullable|NonNull|CheckForNull|PossiblyNull)([[:space:]]+[[:alnum:]_])/__AT__\1__\2/g'"

Objective C

GENERATE_XML           = YES
EXTENSION_MAPPING      = h=objective-c
MACRO_EXPANSION        = YES
EXPAND_ONLY_PREDEF     = YES
PREDEFINED             = NS_ASSUME_NONNULL_BEGIN= NS_UNAVAILABLE= NS_DESIGNATED_INITIALIZER=

Python

To fully support python docstrings formats like the Google Python Style Guide it is recommended to use doxypypy as a filter for Doxygen.

GENERATE_XML           = YES
FILTER_PATTERNS        = *.py="./py_filter.sh"

The contents of py_filter.sh should be:

#!/bin/bash
doxypypy -a -c $1 | sed 's/#        /# /'

The sed command is a workaround for a bug in doxypypy.

Alternatively you can disable MarkDown support and run doxypypy directly:

GENERATE_XML           = YES
FILTER_PATTERNS        = *.py="doxypypy -a -c"
MARKDOWN_SUPPORT       = NO

Support for type hints in Doxygen is still limited: https://github.com/doxygen/doxygen/issues/7320.

PlantUML support

Doxygen will ignore PlantUML diagrams if the path to PlantUML is not set. This is also the case when only the XML format is enabled and Doxygen has no need to call PlantUML. To make sure PlantUML diagrams are exported to XML, make sure to set the path:

PLANTUML_JAR_PATH      = /usr/share/java/plantuml/plantuml.jar