docs(relay): add API documentation for RelayClient and its methods #6970
Conversation
Add detailed Rust doc comments to `RelayClient`, `RelayAddress`, and all public methods to clarify usage, parameters, authentication, and known server limitations for the Relay API client.
|
@groovecoder Thank you for adding these docs 🚀 |
| /// usage stats, and identifying information. | ||
| /// | ||
| /// See: | ||
| /// https://dev.fxprivaterelay.nonprod.cloudops.mozgcp.net/api/v1/docs/redoc/#tag/emails/operation/relayaddresses_retrieve |
There was a problem hiding this comment.
should this link to a .md file or similar in some git repo? This url smells fragile.
There was a problem hiding this comment.
Good idea. I've opened mozilla/fx-private-relay#5903 to publish the API docs to the Relay repo's GitHub Pages site. When we get that url working I'll update this.
| /// managing authorization to call protected endpoints. | ||
| /// | ||
| /// # Authorization | ||
| /// - Clients should user the `FirefoxAccount.getAccessToken()` function |
There was a problem hiding this comment.
I have no idea if/how any of this works in terms of rustdocs etc 😅 - but maybe fxa_client::FirefoxAccount::getAccessToken()? I doubt either of these will render a workable link though.
There was a problem hiding this comment.
I think that's the path to use, but also with brackets: [fxa_client::FirefoxAccount::getAccessToken()]. That should render a correctlink in rustdoc. It won't work for the generated Kotlin/Swift/JS docs, but it's something we could eventually get working.
Also: the parens are optional and backticks are allowed, but ignored.
https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html
There was a problem hiding this comment.
Yeah, I thought about trying to figure it out, but then even if I got the rust docs to link together, I doubt it would carry thru to the Swift or Kotlin docs too, which is the main goal here.
| /// managing authorization to call protected endpoints. | ||
| /// | ||
| /// # Authorization | ||
| /// - Clients should user the `FirefoxAccount.getAccessToken()` function |
There was a problem hiding this comment.
I think that's the path to use, but also with brackets: [fxa_client::FirefoxAccount::getAccessToken()]. That should render a correctlink in rustdoc. It won't work for the generated Kotlin/Swift/JS docs, but it's something we could eventually get working.
Also: the parens are optional and backticks are allowed, but ignored.
https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html
Add detailed Rust doc comments to
RelayClient,RelayAddress, and all public methods to clarify usage, parameters, authentication, and known server limitations for the Relay API client.Pull Request checklist
Any new dependencies are accompanied by a summary of the due diligence applied in selecting them.