Azure / Azure/azure-sdk-for-rust
Generate API.md file(s) for PRs for new API Review Hub
- Dominant language
- Rust
- Stars
- 884
- Forks
- 365
- Avg merge
- 2d 19h
- Merged PRs (30d)
- 109
Description
We need to [onboard](https://github.com/Azure/azure-sdk-tools/wiki/API-Review-Hub-Onboarding) the Rust repo to API Review Hub (ARH). The new `generate_api` tool already supports dumping a markdown file with the public API that has been verified against the JSON token file + the test render PS1.
I'm thinking we dump the following files, though we need to figure out how/when:
* `api/api.md`
* `api/api.comments.patch`
The `api.comments.patch` file is a generator-generated diff since we have the line numbers as we right them out. It contains the comments as a diff since we can't really trust diff'ing later if we had an `api.md` and `api.comments.md`. With a lot of repetition, the diff of comments may not work right.
But with a `.patch` file, we could have a future extension or something to apply/unapply that diff to toggle comments on/off relatively easily.
## Example
### api.md
```rust
pub fn foo();
```
### api.comments.patch
```diff
--- a/foo.rs
+++ b/foo.rs
@@ -0,1 +0,4 @@
+/// Does foo.
+///
+/// What else did you expect?
pub fn foo();
```
Which, when applied, generates:
### api.comments.md
```rust
/// Does foo.
///
/// What else did you expect?
pub fn foo();
```
Contributor guide
Assessment
This issue has not been assessed yet.