Support multiple documentation items with the same name #63
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
The architecture of doxylink was based on a name:item dict, which
doesn't support storing multiple items with the same name. This lead to
several workarounds:
* To support overloaded functions, function items were turned to
name:FunctionList;
* To prevent friend declarations from conflicting with classes, friends
were skipped.
Issues remained nevertheless: C++ allows declaring a class, a function,
and a variable with the same name:
int a;
void a();
class a;
In addition, a common pattern with Qt is to declare properties with the
same name as the getter (Qt itself does this all the time):
class Foo: public QObject
{
Q_OBJECT
Q_PROPERTY(int bar READ bar)
public:
int bar() const;
};
In all the above examples, doxylink was just crashing when parsing the
Doxygen index.
Instead of adding new exceptions, this commit changes the architecture
to allow multiple symbols with the same name. Duplicate names may still
raise an error, but only when one tries to refer to such an entry. This
means that all other symbols in the project can now be used instead of
failing during initialisation.
With this PR, it should be possible to create a domain in the future,
supporting much of the same syntax as the built-in [cpp
domain](https://www.sphinx-doc.org/en/master/usage/domains/cpp.html#cross-referencing)
Supersedes sphinx-contrib#31.
Closes sphinx-contrib#54.
JasperCraeghs
requested changes
Dec 30, 2024
bisect.bisect_left(..., key=) is only since Python 3.10. list[T] is only since Python 3.9. Silenced mypy warnings: * Entry derives from tuple through namedtuple, but __lt__ has a more restrictive signature. Ignoring because the namedtuple parent is an implementation detail. * mypy doesn't understand the bisect_left() call even though it is valid and works. I'm not entirely sure what causes this.
|
Added support for Python < 3.10 (supposedly, the pipeline will tell). I had a small issues with this line: start = bisect.bisect_left(self._entries, name[::-1])MyPy complains as follows: I think this is a bug in I also silenced a MyPy warning for |
JasperCraeghs
approved these changes
Jan 10, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The architecture of doxylink was based on a name:item dict, which doesn't support storing multiple items with the same name. This lead to several workarounds:
Issues remained nevertheless: C++ allows declaring a class, a function, and a variable with the same name:
In addition, a common pattern with Qt is to declare properties with the same name as the getter (Qt itself does this all the time):
In all the above examples, doxylink was just crashing when parsing the Doxygen index.
Instead of adding new exceptions, this commit changes the architecture to allow multiple symbols with the same name. Duplicate names may still raise an error, but only when one tries to refer to such an entry. This means that all other symbols in the project can now be used instead of failing during initialisation.
With this PR, it should be possible to create a domain in the future, supporting much of the same syntax as the built-in cpp domain
Supersedes #13.
Closes #54.