cargo-public-api icon indicating copy to clipboard operation
cargo-public-api copied to clipboard

`use`ed types from external crates have incorrect local names & paths

Open repi opened this issue 3 years ago • 0 comments

Ran into multiple problems regarding use statements on types (not not pub use) where the public API listing will be referring internal naming of the type within the module rather than the public type it is actually referring to.

This input:

use macaw as internal_name_for_a_crate;
use macaw::Conformal3;
use macaw::Conformal3 as WeirdName;

pub fn test1(_transform: Conformal3) {}
pub fn test2(_transform: WeirdName) {}
pub fn test3(_transform: macaw::Conformal3) {}
pub fn test4(_transform: internal_name_for_a_crate::Conformal3) {}

pub enum Test {
    V1(Conformal3),
    V2(WeirdName),
    V3(macaw::Conformal3),
    V4(internal_name_for_a_crate::Conformal3),
}

Generates this output:

pub enum a2::Test
pub enum variant a2::Test::V1(Conformal3)
pub enum variant a2::Test::V2(WeirdName)
pub enum variant a2::Test::V3(macaw::Conformal3)
pub enum variant a2::Test::V4(internal_name_for_a_crate::Conformal3)
pub fn a2::test1(_transform: Conformal3)
pub fn a2::test2(_transform: WeirdName)
pub fn a2::test3(_transform: macaw::Conformal3)
pub fn a2::test4(_transform: internal_name_for_a_crate::Conformal3)
pub mod a2

Which I believe needs to be this to reflect what the public API actually is and not "leak" any internal naming within the crate module.

pub enum a2::Test
pub enum variant a2::Test::V1(macaw::Conformal3)
pub enum variant a2::Test::V2(macaw::Conformal3)
pub enum variant a2::Test::V3(macaw::Conformal3)
pub enum variant a2::Test::V4(macaw::Conformal3)
pub fn a2::test1(_transform: macaw::Conformal3)
pub fn a2::test2(_transform: macaw::Conformal3)
pub fn a2::test3(_transform: macaw::Conformal3)
pub fn a2::test4(_transform: macaw::Conformal3)
pub mod a2

Rustdoc HTML handles the the function output here correctly referring to all of them as Conformal3 but all linking to the macaw::Conformal3 docs page. I think in our case we would want it to be directly fully qualified names of macaw::Conformal3 everywhere where used.

In addition, even in the case of a single use crate::type can be problematic because one module could do that and use that type in a public API, and another module in the same crate could do use crate2::type and export another public API. So believe all imported used types need to be listed as fully qualified as crate::<potential-path>::name in the listing.

repi avatar Sep 13 '22 22:09 repi