-
Notifications
You must be signed in to change notification settings - Fork 50
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Problem with overloaded functions #32
Comments
duplicate of #13. No worries about the duplicate, I'm doing that here so I know which ones to close when its fixed ;) TBH I haven't actually looked very closely at the problem. I wouldn't be surprised if there is already a solution. If you're willing to hunt a little, what you can do to test
Just dont I think the error above is actually saying the fix. In one of them, it should be .. doxygenfunction:: array<Point> fistro::PAA(array<Point>, int) and in the other .. doxygenfunction:: std::vector<Point> fistro::PAA(std::vector<Point>, int) (whereas currently, Exhale is naively doing If you can help identify what are valid signatures for Breathe I'd be very grateful and should be able to get a fix in here pretty quickly. I remember I gave it a brief stab and wasn't able to get anything working manually though, and then kind of forgot about it x0 |
P.S. if I remember correctly Breathe is exceptionally sensitive to whitespace, e.g. there has to be a space between the |
After diving a little bit among the generated .rst files. I have observed the following: I have one file that gathers the information for the dimensionality namespace, this file contains two references to the function PAA, however they do not seem to make any differences, as they are just pointing to the same ref.
Additionally, I also have an unique .rst file that defines the PAA function (In some how I would expect two flavours of this file).
I have tried to add the whole signature to this second file, where the function is being referenced, however I have got the following error message: |
It does, thank you. Try editing the other file. I'm overwriting the first function with the second one. Which one is arbitrary (order based on doxygen's I'll need to parse function signatures... |
Wait actually I'm confused now. I think this is two separate issues, one is the file defining the function is getting overwritten. But what namespace is this function in? a) |
Sorry, copy paste error, both are fistro namespace (editing the previous message) |
I'm hit with the same issue. One of my classes have two methods of the same name: void kill();
static void kill(aid_t pid); There is no mention of these functions in my build logs: https://framagit.org/simgrid/simgrid/-/jobs/204729 If I dump my objects.inv (using
As one could expect, a reference to :cpp:func: |
I am working on this today, and hope to solve this once and for all! |
@mquinson sorry I misunderstood your problem. For your situation you need to specify the parameter types, I think for your case you should be able to do :cpp:function:`simgrid::s4u::Actor::kill(aid_t)` Or at least that's my understanding. Some gotchas are sensitivity to whitespace like Please report back so that if not successful we can open an issue upstream. This issue is actually about exhale failing on free functions (not scoped to any classes or structs), but I'm having trouble deciphering the exact rules breathe needs because they don't mirror what doxygen actually produces :( Note this issue does affect your framework, e.g. |
Unfortunately, it does not seem to work:
leads to
while
leads to
Maybe it is because the () are added automatically. I seem to remember that I added a configuration option to do so somewhere, but I fail to find it again, sorry. Here is my config: |
I found the configuration item back, but it's not helping. If I add |
Ok I think I got to the bottom of this @mquinson 😄
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 70f5238..1ead91c 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -58,7 +58,7 @@ exhale_args = {
"containmentFolder": "./api",
"rootFileName": "library_root.rst",
"rootFileTitle": "SimGrid Full API",
- "doxygenStripFromPath": "..",
+ "doxygenStripFromPath": "../..",
# Suggested optional arguments
"createTreeView": True,
# TIP: if using the sphinx-bootstrap-theme, you need
@@ -83,7 +83,7 @@ exhale_args = {
XBT_ATTRIB_DEPRECATED_v322(m)= \
XBT_ATTRIB_DEPRECATED_v323(m)= \
XBT_ATTRIB_DEPRECATED_v324(m)=
-
+
"""
}
@@ -154,7 +154,7 @@ htmlhelp_basename = 'SimGrid-doc'
html_context = {
"display_gitlab": True, # Integrate Gitlab
- "gitlab_host": "framagit.org",
+ "gitlab_host": "framagit.org",
"gitlab_user": "simgrid",
"gitlab_repo": "simgrid",
"gitlab_version": "master", # Version
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 93d9c1a..5ffa70c 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -9,7 +9,7 @@ Welcome to SimGrid's documentation!
Simulating Algorithms <tuto_s4u.rst>
Simulating MPI Apps <usecase_mpi.rst>
-
+
.. toctree::
:maxdepth: 1
:caption: Getting Started:
@@ -25,6 +25,44 @@ Welcome to SimGrid's documentation!
API <api/library_root.rst>
+Link Tests
+==========
+
+The Desired Links (Second Sometimes Breaks)
+-------------------------------------------
+
+- See :cpp:func:`simgrid::s4u::Actor::kill` for the no parameter version.
+- See :cpp:func:`void simgrid::s4u::Actor::kill(aid_t)` for the parameter version.
+
+Using Sphinx C++ Domain
+-----------------------
+
+When a (member) function is referenced using just its name, the reference
+will point to an arbitrary matching overload.
+The :rst:role:`cpp:any` and :rst:role:`cpp:func` roles will an alternative
+format, which simply is a complete function declaration.
+This will resolve to the exact matching overload.
+As example, consider the following class declaration:
+
+.. cpp:namespace-push:: overload_example
+.. cpp:class:: C
+
+ .. cpp:function:: void f(double d) const
+ .. cpp:function:: void f(double d)
+ .. cpp:function:: void f(int i)
+ .. cpp:function:: void f()
+
+References using the :rst:role:`cpp:func` role:
+
+- Arbitrary overload: ``C::f``, :cpp:func:`C::f`
+- Also arbitrary overload: ``C::f()``, :cpp:func:`C::f()`
+- Specific overload: ``void C::f()``, :cpp:func:`void C::f()`
+- Specific overload: ``void C::f(int)``, :cpp:func:`void C::f(int)`
+- Specific overload: ``void C::f(double)``, :cpp:func:`void C::f(double)`
+- Specific overload: ``void C::f(double) const``, :cpp:func:`void C::f(double) const`
+
+.. cpp:namespace-pop::
+
Indices and tables
==================
So basically, assuming you're on say
However, this is where I need your help. I'm experiencing this really weird behavior where every other build will fail. So if I
Then if i run again, success. Run again, same failure. Do you experience anything like that or does it just reliably work? |
Damn. Sorry. TL;DR after the fact:
|
Here are the version I was using so far (the one provided by Debian testing):
Exhale was installed with pip3 as it's not packaged yet. With them, the compilation of your tests produce:
I will uninstall the debian packages, move to pip for all of them, and report what I get in another post.
|
It took me a while to get I confirm what you have, where every second build in the same tree produces
Isn't that a bit weird that unabridged_api is not listed in a toctree when it fails? |
Most excellent, thank you for confirming @mquinson! Yes I'm really confused by this behavior, especially the unabridged API shenanigans. I'm going to see what I can do to reproduce this using a reduced example with / without exhale. FWIW, it's a little late now, but next time you want to do a quick version test So for production, are you needing to link to this from an rst doc, or a docstring in the code itself? If the former, it seems not possible. But if the latter, you should be able to use |
Hello, I know about https://simgrid.frama.io/simgrid/tuto_s4u.html#lab-3-fixed-experiment-duration The link to simgrid::s4u::Actor::kill(aid_t) is working there. Thanks for your help, |
Hi there,
I'm just using Exhale to document a small c++ library, the tool works pretty well except for overloaded functions. When it tries to parse them, it does not seem to be able to choose the right definition, as it produces the following warning message.
WARNING: doxygenfunction: Unable to resolve multiple matches for function "tsa::dimensionality::PAA" with arguments () in doxygen xml output for project "TSA" from directory: /grijander/repositories/fistro-lib/build/doc/doxygen/xml. Potential matches: - array<Point> fistro::PAA(array<Point>, int) - std::vector<Point> fistro::PAA(std::vector<Point>, int)
Actually, it includes both function definitions in the list of available functions, but If you click on any of them, I get a yellow/orange warning box with the same text as above.
Do you know any work-around to overcome this problem.
Thanks in advance, you have done a great work.
Antonio Vilches.
The text was updated successfully, but these errors were encountered: