ferristseng / rust-ipfs-api

IPFS HTTP client in Rust
Apache License 2.0
246 stars 68 forks source link

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

Closed nathan-at-least closed 1 year ago

nathan-at-least commented 1 year ago

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 commented 1 year ago

Thanks! This looks great!

iamjpotts commented 1 year ago

@ferristseng did this change break the CI build?