Move derive macros docs to scylla crate #907
Merged
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
|
After this is merged, we should release a new version, so that users are able to find documentation. |
piodul
requested changes
Jan 12, 2024
There was a problem hiding this comment.
While the documentation in the scylla crate looks much better, it looks like the docstrings from multiple crates are still being squashed. For example, the message about the macro being documented in the scylla crate still appears in scylla::macros::ScyllaCql:
However, I can't find anything on the net about overriding docstrings on reexport, so I can't suggest any way to get rid of them (if it is possible at all). As we discussed on slack, let's at least make the message from scylla-macros more separated from the rest by putting a separator at the end of the docstrings in scylla.
Lorak-mmk
force-pushed
the
workaround_macros_docs
branch
from
a7c7b06 to
9261bed
Compare
This will be required to move documentation of serialization macros into scylla crate. This in turn is required to workaround the issue that documentation for those macros is not rendered on docs.rs correctly.
When both original item and re-export are documented, documentations are merged. Before this commit, both original item and re-export were documented - identically or at least very similarly. This caused docs in scylla-cql crate to be copy-pasted twice. Replace docs with stubs pointing to the scylla crate to avoid it and point users to proper documentation.
This module is now so small it doesn't make much sens to keep it in separate file.
Documentation was moved from scylla-cql to scylla, which made some paths used in those docs incorrect. This commit updates paths to correct ones.
Rustdocs merges documentation of re-exports with documentation of original item. Because of this there is a need for separator, so that stubs from scylla-macros crate are not mixed up with docs present in scylla crate.
Without those lines, whole doc for an item is merged and shown in the summary, which makes it hard to read.
Lorak-mmk
force-pushed
the
workaround_macros_docs
branch
from
9261bed to
7933112
Compare
|
v2
|
piodul
approved these changes
Jan 12, 2024
Closed
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.
This PR moves docs for serialization / deserialization related derive macros from scylla-cql crate to scylla crate.
This is done to work around the issue that this documentation was not rendered correctly on docs.rs for scylla crate.
It's hard to tell why that is exactly - it's probably a bug / limitation in rustdoc.
It looks like when we have item X in crate A, re-export X as Y in crate B and document it, and re-export Y az Z in crate C,
Y's docs won't be rendered in crate C, only X's and Z's will.
Fixes: #904
Pre-review checklist
./docs/source/.Fixes:annotations to PR description.