Azure / Azure/azure-sdk-for-rust

Generate API.md file(s) for PRs for new API Review Hub

Open
#5,210 0 comments 1 reaction 1 assignee Claimed by @heaths View on GitHub
EngSys
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.