Overloaded functions not resolved.

[tjienta]

When generating documentation for my project I get the following errors for overloaded functions:

doxygenfunction: Unable to resolve multiple matches for function “tt::operator<<” with arguments (std::ostream&, FontWeight const&) in doxygen xml output for project “TTauri” from directory: C:/Users/Tjienta/CMakeBuilds/1f9f7e79-3587-4ae4-b76b-4cfa997cb5c7/build/x64-Debug/TTauri/src/xml. Potential matches:

- std::ostream &operator<<(std::ostream &lhs, AudioDevice_state const &rhs)
- std::ostream &operator<<(std::ostream &lhs, FontWeight const &rhs)
- std::ostream &operator<<(std::ostream &lhs, KeyboardModifiers const &rhs)
- std::ostream &operator<<(std::ostream &lhs, KeyboardVirtualKey const &rhs)
- std::ostream &operator<<(std::ostream &lhs, TextDecoration const &rhs)
- std::ostream &operator<<(std::ostream &lhs, ThemeMode rhs)
- std::ostream &operator<<(std::ostream &lhs, cell_address const &rhs)
- std::ostream &operator<<(std::ostream &lhs, command const &rhs)
- std::ostream &operator<<(std::ostream &lhs, const URL &rhs)
- std::ostream &operator<<(std::ostream &lhs, datum_type_t rhs)
- std::ostream &operator<<(std::ostream &lhs, glob_token_t const &rhs)
- std::ostream &operator<<(std::ostream &lhs, glob_token_type_t const &rhs)
- std::ostream &operator<<(std::ostream &lhs, source_code_ptr const &rhs)
- std::ostream &operator<<(std::ostream &lhs, tokenizer_name_t rhs)
- template<typename T, int M> std::ostream &operator<<(std::ostream &lhs, fixed<T, M> const &rhs)
- template<typename T, int N> std::ostream &operator<<(std::ostream &os, results<T, N> const &r)
- template<typename Tag, typename ...InfoTags> std::ostream &operator<<(std::ostream &lhs, trace_data<Tag, InfoTags...> const &rhs)

I've tried many ways of rewriting the doxygen statement until it works:

• The whitespace between type and reference & is required.
• The argument name after the reference is required.

Generated incorrect doxygenfunction statement:

.. doxygenfunction:: tt::operator<<(std::ostream&, FontWeight const&)

Functioning doxygenfunction statement (Both whitespace and the parameter names are required):

.. doxygenfunction:: tt::operator<<(std::ostream &lhs, FontWeight const &rhs)

These are the packages that are installed on my system

alabaster==0.7.12
Babel==2.8.0
beautifulsoup4==4.9.1
breathe==4.19.2
bs4==0.0.1
certifi==2020.6.20
chardet==3.0.4
colorama==0.4.3
docutils==0.16
exhale==0.2.3
idna==2.10
imagesize==1.2.0
Jinja2==2.11.2
lxml==4.5.2
MarkupSafe==1.1.1
packaging==20.4
Pygments==2.6.1
pyparsing==2.4.7
pytz==2020.1
requests==2.24.0
six==1.15.0
snowballstemmer==2.0.0
soupsieve==2.0.1
Sphinx==3.1.2
sphinx-rtd-theme==0.5.0
sphinxcontrib-applehelp==1.0.2
sphinxcontrib-devhelp==1.0.2
sphinxcontrib-htmlhelp==1.0.3
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==1.0.3
sphinxcontrib-serializinghtml==1.1.4
urllib3==1.25.10

conf.py.in

# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))


# -- Project information -----------------------------------------------------

project = 'TTauri'
copyright = '2020, Pokitec'
author = 'Tjienta Vara'

# The full version, including alpha/beta/rc tags
release = '1.0'


# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    "sphinx_rtd_theme",
    "breathe",
    "exhale"
]

breathe_projects = {
    "TTauri": "@SPHINX_XML_INPUT@"
}

breathe_default_project = "TTauri"

import os.path

exhale_args = {
    "containmentFolder":     os.path.normpath("@CMAKE_CURRENT_SOURCE_DIR@/api"),
    "rootFileName":          "ttauri_api.rst",
    "rootFileTitle":         "TTuari API",
    "doxygenStripFromPath":  "..",
    # Suggested optional arguments
    "createTreeView":        True,
    # TIP: if using the sphinx-bootstrap-theme, you need
    # "treeViewIsBootstrap": True,
    "exhaleExecutesDoxygen": False,
    #"exhaleDoxygenStdin":    "INPUT = @SPHINX_XML_INPUT@"
}

primary_domain = "cpp"

highlight_language = "cpp"

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []


# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

The actual function definition/declaration.

inline std::ostream& operator<<(std::ostream& lhs, FontWeight const& rhs) {
    return lhs << to_string(rhs);
}

[svenevs]

Thanks for the report, this is definitely out of your control / I'm sorry it's so frustrating!

Can you please try walking backward and installing older versions of breathe and if you find a version that works let me know? The main code responsible for this is here

https://github.com/svenevs/exhale/blob/58c6c771fe021d7487644a30c2575b3fcf1ae94b/exhale/graph.py#L245-L250

Overloads used to be happy, but it looks like breathe has updated to want the parameter names (e.g., lhs and rhs). If that's what's going on it should be fixable by special casing on breathe version number. It's always been rather sensitive, for example whitespace has to match exactly what breathe stored, not necessarily what's in the doxygen XML.

Long term I will need to step up and add refid lookup support to breathe, some template overloads are still not possible. But things are not good for me right now / those changes will be substantive.

[svenevs]

Hmm, not sure if that's the real problem. If you walk back to 4.13 and it's still broken then it's something else (that's the last version I know was working). I'm looking at tt::operator vs std::operator being mentioned by breathe. Your corrected signature implies we can still use tt:: aka hopefully it's the original diagnosis I suggested above about needing parameter names now, but that may not be the case...

[tjienta]

Sadly. When I rolled back breath to 4.13 it used a depricated API mathbase So I rolled back sphinx to 2.4.4 But then I got a "AttributeError: 'str' object has no attribute 'get_display_string'" error So I tried rolling back sphinx to 1.7.9 due to the recommendation in the exhale bug report for that But rolling back to that gives a dependency conflict and getting the following error:

Exception occurred:
    File "c:\program files (x86)\python37-32\lib\site-packages\breathe\renderer\sphinxrenderer.py", line 89, in DomainDirectiveFactory
      'union': (cpp.CPPUnionObject, 'union'),
  AttributeError: module 'sphinx.domains.cpp' has no attribute 'CPPUnionObject'
  The full traceback has been saved in C:\Users\Tjienta\AppData\Local\Temp\sphinx-err-2kro_3fi.log, if you want to report the issue to the developers.
  Please also report this if it was a user error, so that a better error message can be provided next time.
  A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
  ninja: build stopped: subcommand failed

Is there a known working combination of exhale, breath, sphinx versions?

[svenevs]

Is there a known working combination of exhale, breath, sphinx versions?

Oh my, thank you for trying!

I will need to look closer into this hopefully soon, was able to get skeleton / hacky version of getting the parameter names in there in #91 but need to also figure out the working combinations ... fairly certain variable names were skipped for a reason but not entirely sure.