Skip to content
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

Various fixes to C++ domain and format_signatures #377

Merged
merged 9 commits into from
Aug 3, 2024
Merged

Conversation

jbms
Copy link
Owner

@jbms jbms commented Aug 2, 2024

  • Make C++ doc comment parsing more robust and don't rely on raw_comment from clang
  • Fix handling of whitespace in format_signatures
  • Remove unnecessary data from env to improve parallel build efficiency
  • Fix building with Sphinx 8.0.2
  • Fix C++ apigen handling of unnamed template parameters
  • Fix :any: xrefs to C macros
  • Support undocumented enumerators

@jbms jbms requested a review from 2bndy5 August 2, 2024 19:52
jbms added 9 commits August 2, 2024 12:59
For unknown reasons, in some cases libclang fails to include doc
comments in the `Cursor.raw_comment` field when they are present.

As a workaround, don't rely on the `Cursor.raw_comment` field and
instead parse doc comments from the surrounding tokens directly.

This also makes the parsing of the raw comment into doc comments handle
the case of mixed doc comment types.
libclang seems to generate UNEXPOSED_DECL cursors for
instantiations (not specializations) of variable templates in certain
cases/with certain versions of libclang.

These cursors result in a JSON entity description that is identical that
produced from the cursor corresponding to the original definition. These
are now excluded as duplicates based on the assumption that they will
occur after the "real" cursor.
When aligning the pre-formatted and post-formatted text, ignore
whitespace for better alignment.
Previously, the cppreference data and the json schema data were stored
on the `env` object.

Data on the `env` object is pickled and sent back separately with every
chunk of documents that are processed by a worker process. Only
information that relates to the specific documents that have been read
should be stored on the `env` object.
Previously, unnamed template parameters were incorrectly assigned a name
of `"None"`.
@jbms
Copy link
Owner Author

jbms commented Aug 2, 2024

This PR combines a number of independent fixes. Please refer to the independent commit descriptions for details.

Copy link

codecov bot commented Aug 2, 2024

Codecov Report

Attention: Patch coverage is 85.80645% with 22 lines in your changes missing coverage. Please review.

Project coverage is 76.07%. Comparing base (9ec088e) to head (1932164).
Report is 21 commits behind head on main.

Files with missing lines Patch % Lines
sphinx_immaterial/apidoc/cpp/api_parser.py 89.13% 15 Missing ⚠️
...x_immaterial/apidoc/cpp/external_cpp_references.py 0.00% 3 Missing ⚠️
sphinx_immaterial/apidoc/format_signatures.py 0.00% 2 Missing ⚠️
sphinx_immaterial/apidoc/json/domain.py 85.71% 1 Missing ⚠️
sphinx_immaterial/search_adapt.py 0.00% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main     #377      +/-   ##
==========================================
+ Coverage   67.19%   76.07%   +8.87%     
==========================================
  Files          68       68              
  Lines        8515     8598      +83     
==========================================
+ Hits         5722     6541     +819     
+ Misses       2793     2057     -736     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

Copy link
Collaborator

@2bndy5 2bndy5 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. I wish libclang had a more intuitive way of getting doc comments, but I think that's more the C/C++ language's fault.

@jbms jbms merged commit cbbf71f into main Aug 3, 2024
26 checks passed
@jbms jbms deleted the fix-cpp-apigen branch August 3, 2024 21:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants