Skip to content

Switch from use … as IpfsClient to type aliases for clearer API docs. #131

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged

Conversation

nathan-at-least
Copy link

I find the generated API docs for use path::Foo as Bar to be confusing compared to type aliases.

Current docs from master branch

Currently in master, the identifier ipfs_api_backend_hyper::IpfsClient is defined as:

pub use crate::{backend::HyperBackend as IpfsClient, error::Error};

The rendered API docs look like this:

Screenshot 2023-05-23 11 09 19

What is the relationship of IpfsClient to HyperBackend?

I believe the root problem here is actually a rustdoc problem, but this PR uses type aliases to work around the ambiguity.

With type aliases (this PR) in HyperBackend

By introducing type aliases first of all the alias is documented explicitly:

Screenshot 2023-05-23 11 19 39

-then when clicking through to the definition of HyperBackend the API is unambiguous:

Screenshot 2023-05-23 11 19 26

With type aliases (this PR) in ActixBackend

The equivalent for ActixBackend has this type alias:

Screenshot 2023-05-23 11 31 12

-and this underlying backend API:

Screenshot 2023-05-23 11 31 00

@ferristseng
Copy link
Owner

Thanks! This looks great!

@iamjpotts
Copy link
Contributor

@ferristseng did this change break the CI build?

iamjpotts added a commit to iamjpotts/rust-ipfs-api that referenced this pull request Aug 31, 2023
iamjpotts added a commit to iamjpotts/rust-ipfs-api that referenced this pull request Aug 31, 2023
ferristseng added a commit that referenced this pull request Aug 31, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants