Merged
Conversation
Contributor
My `make preview` output:
So there are some Duplicate C++ declaration errors and some warnings. |
wprzytula
reviewed
Feb 27, 2026
Comment on lines
+129
to
+143
| def _generate_groups(outdir, groups, project): | ||
| """Write structs docs in the designated outdir folder""" | ||
| for obj in groups: | ||
| with open(outdir / f"group.{obj}.rst", "w") as t_file: | ||
| t_file.write( | ||
| obj | ||
| + "\n" | ||
| + "=" * len(obj) | ||
| + "\n\n" | ||
| + ".. doxygengroup:: " | ||
| + obj | ||
| + "\n :project: " | ||
| + breathe_default_project | ||
| + "\n :content-only:" | ||
| ) |
Contributor
There was a problem hiding this comment.
❓ How did you know how to do that?
- similar to something else in the code?
- documentation?
- AI?
Please explain this in a comment.
Contributor
Author
There was a problem hiding this comment.
AI. I ofc read the code to see if it looks reasonable + tested that it works.
I don't think its useful to describe in the comments "how I found some informations". Comments should explain how something works, and sometimes why it works that way.
Contributor
|
Additionally, But it no longer reproduces after I did |
Contributor
|
Rendered documentation looks bad (visually). |
Contributor
Author
I did have similar issues on the day when I was working on this PR! |
Contributor
Author
One warning about sphinx 9 is expected - it comes from a dependency. Doxygen config warnings are surprising. I also experienced such warnings, so I updated the config to get rid of them (there is a commit with that in this PR). |
Contributor
Author
Did it regress due to my PR? Or is it just a general observation? |
This was a duplicate of doc comment for cass_data_type_sub_type_count function.
Contributor
Author
|
Rebased on master. |
Contributor
On your PR, straight after running
❯ doxygen --version |
Contributor
It was such before, too. No regression in this regard. |
Contributor
Author
|
In CI I also see Doxygen warnings: So I guess I updated config to a too-new format. I'll try to adjust that. |
There were some errors in the documentation: missing parameters docs, wrong parameter name, @return docs for functions returning void. All of this was resulting in Doxygen warnings. This commit fixes all those issues.
This resulted in a warning, but would become a hard error in Sphinx v9. This commit fixes the warning by using python paths as they were intended, instead of string concatenation. After this commit there is only 1 warning left when building docs, and it is not in our code (Breathe extension will need to fix it).
We want to add all items from cassandra.h that are missing from rendered docs. For many, we can't use `@memberof`, because they don't really fit any struct. A good tool for this are Doxygen groups, but right now our documentation won't render them. This commit adds support for rendering them.
Some of them don't really belong to any struct, and so have not been exported. The solution is to introduce new groups for them. For now, I introduced two: one for logging-related stuff, one for everything else.
It contains stuff like int aliases, that were missing from docs until now.
It contains CassError enum and related types: CassWriteType, CassErrorSource, and functions that operate on them.
It contains types used in cass_alloc_set_functions function, and the function itself.
Fields of CassAuthenticatorCallbacks used type aliases that were not documented. This commit adds them to docs of this struct.
I don't see a better place for them.
CassConsistency appears in many functions, operating on various types. Because of that I think it deserves its own section.
CassValueTypes appears in functions belonging to more than one type, and quite many of them, so I think it deserves its own section.
Some enums were not present in docs. I added them to relevant section.
This commit adds missing logging-related types to the logging section. A struct can't be duplicated in docs, and CassLogMessage is a struct so it had its own section. To fix that, I adjusted logic in conf.py: now, if a struct is present in some group, it will not get its own section.
Contributor
Author
|
Contributor
This is what I get now:
|
Contributor
Author
|
Doxygen config warnings are harmless, and depend on the version, We can sort it out some other time. |
Contributor
I'm running |
Before that `make clean` didn't clean all files produced while building docs. This commit fixes that.
Contributor
Author
|
I added a commit that fixes |
wprzytula
approved these changes
Mar 2, 2026
This file contains hidden or 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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
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.
I wanted to fix #392 , and that's what the first commit does.
When working on that, I noticed a lot of other issues with our API docs: bugs in doc comments, many types not rendered in documentation, warnings when building docs...
Other commits fix all of such issues that I found. Now, each driver type should be present in docs, and clickable in function signatures.
For reviewers: I advise building the docs, and looking at rendered API docs pages yourself.
Fixes: #392
Pre-review checklist
I have implemented Rust unit tests for the features/changes introduced.I have enabled appropriate tests inMakefilein{SCYLLA,CASSANDRA}_(NO_VALGRIND_)TEST_FILTER.Fixes:annotations to PR description.