docgen/website: show deprecated function warnings on docs website #584
Conversation
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. |
|
Thanks for the review 🌠 I'll iterate this weekend. |
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()`.
Simplify the logic by handling the case where `prev` is a comment that may/may not have a feature req previous to the comment up-front. Then, when we're looking at a `prev` that wasn't a comment, but was `kind == expression_statement` we can recurse with `prev_prev` to handle it as a comment that may/may not have a feature req previous to itself. Lastly, if we know we don't have a comment and we don't have an expression statement, try to see if we have a bare feature requirement. We know cbindgen won't make a comment ahead of these and so can disregard `prev_prev` for this case.
The `api.json` data is updated to add the parsed deprecation messages.
cpu
force-pushed
the
ci/cpu-deprecate-notes
branch
from
746a69e to
968640d
Compare
tools/src/bin/docgen/main.rs
Outdated
| // expression-like preprocessor attributes on function decls. | ||
| if prev.kind() == "expression_statement" { | ||
| return match prev_prev { | ||
| Some(prev_prev) => comment_and_requirement(prev_prev, src), |
There was a problem hiding this comment.
The introduction of recursion seems kind of sudden, maybe deserves its own commit?
tools/src/bin/docgen/main.rs
Outdated
| maybe_comment = Comment::new(prev_prev, src).ok(); | ||
| // In the simple case, `prev` is a comment and `prev_prev` may | ||
| // be a feature requirement. | ||
| if let Ok(comment) = Comment::new(prev, src) { |
There was a problem hiding this comment.
This commit is still a little confusing to me, it seems to have a bunch of things going on that interact, making it hard to understand what the logical changes are. Suggest at least splitting out a commit that only does the maybe_comment.is_none() inversion thing?
| @@ -48,57 +45,6 @@ struct ApiDocs { | |||
| aliases: Vec<TypeAliasItem>, | |||
| } | |||
|
|
|||
| impl ApiDocs { | |||
There was a problem hiding this comment.
I don't see why it makes sense to do these in the same commit? It certainly makes reviewing harder...
| Item::Function(item) => &mut item.metadata, | ||
| Item::Extern(item) => &mut item.metadata, | ||
| }; | ||
| metadata.crosslink(anchors) |
| let comment = match prev_prev { | ||
| Some(prev_prev) => Comment::new(prev_prev, src).ok(), | ||
| None => None, | ||
| }; |
There was a problem hiding this comment.
Nit: use .map() more to avoid the None => None branches?
| Some(prev_prev) => Comment::new(prev_prev, src).ok(), | ||
| None => None, | ||
| }; | ||
| let prev_prev_prev = prev_prev.and_then(|prev_prev| prev_prev.prev_named_sibling()); |
There was a problem hiding this comment.
Consider making this part of the previous match?
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: