docgen/website: show deprecated function warnings on docs website #584
+2,639
−208
Conversation
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
Maybe we should start checking in the data JSON and set up CI to verify that a fresh That way we could review the JSON diffs alongside code updates (both to the tool & the lib) to see if we accidentally lose items/comments/etc. |
djc
reviewed
Jul 11, 2025
|
Thanks for the review 🌠 I'll iterate this weekend. |
cpu
force-pushed
the
ci/cpu-deprecate-notes
branch
from
746a69e to
968640d
Compare
djc
reviewed
Jul 14, 2025
Will try to return to this soon. The weather has been too nice to spend weekends indoors 😆 |
This way we can review updates to the website documentation data alongside code changes. ``` $ git rev-parse HEAD 3f5b127 $ cargo run --manifest-path tools/Cargo.toml --bin docgen > ./website/static/api.json Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.06s Running `target/debug/docgen` ```
Now that we're checking in the `api.json` content generated by the `docgen` tool the expectation is that there shouldn't be any uncommitted diffs when running the tool fresh in CI.
But update the package/upload and deploy steps to only happen for rustls-ffi's main branch.
Also rename some bindings for clarity. The input node is the previous sibling node for a to-be-documented item so call it `prev`. We also look at `prev`'s previous sibling node, so call those instances `prev_prev`.
We also only care about named (not anonymous) sibling nodes, so use just `prev_named_sibling()` instead of the mix of `prev_sibling()` and `prev_named_sibling()`.
Handle the simple case up-front.
We can handle the case where prev is an expression_statement by recursing with `prev_prev`.
When we know prev wasn't a comment or an expression statement preceded by a comment.
The `api.json` data is updated to add the newly parsed deprecation messages.
cpu
force-pushed
the
ci/cpu-deprecate-notes
branch
from
968640d to
f349f0d
Compare
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.
Updates the
docgentool from thetoolscrate to parse theDEPRECATED_FUNCmacro invocations ahead of function declarations. Once parsed we can pull out the argument message and include that in the JSON data generated by the tool.With the deprecated messages the
websiteZola templates can reference them to add a note of the deprecation in the TOC and to add a warning banner to the item's docs rendering.Resolves #582
Examples: