Skip to content
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

rustdoc: reexported type aliases are not preserved in function signatures #15823

Open
ghost opened this issue Jul 20, 2014 · 16 comments
Open

rustdoc: reexported type aliases are not preserved in function signatures #15823

ghost opened this issue Jul 20, 2014 · 16 comments
Assignees
Labels
C-bug Category: This is a bug. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@ghost
Copy link

ghost commented Jul 20, 2014

The recently added iterate function uses the Iterate type alias as its result type. It is correctly displayed in http://static.rust-lang.org/doc/master/core/iter/fn.iterate.html but not in http://static.rust-lang.org/doc/master/std/iter/fn.iterate.html.

@huonw huonw added A-ARM and removed A-ARM labels Jul 20, 2014
@ghost
Copy link
Author

ghost commented Jul 20, 2014

Also, the lifetime 'a is dropped from the list of parameters for iterate.

@bluss
Copy link
Member

bluss commented Jul 20, 2014

Related to #15099

@mahkoh
Copy link
Contributor

mahkoh commented Oct 6, 2014

This must be fixed because it makes writing portable programs impossible.

@huonw
Copy link
Member

huonw commented Oct 6, 2014

@mahkoh, how does a rustdoc rendering bug affect the portability of a program?

@mahkoh
Copy link
Contributor

mahkoh commented Oct 6, 2014

@huonw: Type aliases are often used to hide platform specific types. If the documentation shows that a function takes a i64, but it actually takes a c_long, then it won't compile on platforms where c_long is not i64.

@icorderi
Copy link
Contributor

I just run into this issue. In my case, the types being show by the doc are not even public.

You can see the problem on this doc output.
Note that Command_Algorithm should read Algorithm.
The title of the types are always correct, its the method and impl signature that show wrong.

I don't know if it helps, but the types are being aliased here in my code.

@steveklabnik
Copy link
Member

This file:

pub use std::result::Result as Lol;

still mis-renders:

2015-11-07-081909_380x121_scrot

though as @icorderi mentions, the titles are correct.

@steveklabnik steveklabnik added T-dev-tools Relevant to the dev-tools subteam, which will review and decide on the PR/issue. and removed T-tools labels May 18, 2017
@Mark-Simulacrum Mark-Simulacrum added the C-bug Category: This is a bug. label Jul 21, 2017
@steveklabnik
Copy link
Member

Triage: no changes since my last comment

@GuillaumeGomez
Copy link
Member

Seems to be working now so closing.

@svartalf
Copy link

I don't think this issue is fully fixed (correct me if I'm wrong); for example, for heim docs.rs does not render type alias correctly, resulting in a weirdly gibberish output: https://docs.rs/heim/0.0.10/heim/cpu/struct.CpuFrequency.html#method.current

Type alias is used in the sub-crate code: https://github.com/heim-rs/heim/blob/095768ff6a580b27727b6958521392bb5f86a443/heim-cpu/src/freq.rs#L20-L22

And whole this crate is re-exported with #[doc(inline)] later at the facade crate: https://github.com/heim-rs/heim/blob/v0.0.10/heim/src/lib.rs#L59-L61

Docs for sub-crate are rendered almost correctly: https://docs.rs/heim-cpu/0.0.10/heim_cpu/struct.CpuFrequency.html#method.current
It does not has an active link, though, which might be part of the problem.

@svartalf
Copy link

Here is a minimally working example for this issue: https://github.com/svartalf/rust-issue-15823

@GuillaumeGomez GuillaumeGomez self-assigned this Feb 29, 2020
@GuillaumeGomez
Copy link
Member

It works fine for me? Version 1.43.

@svartalf
Copy link

svartalf commented Mar 4, 2020

@GuillaumeGomez thanks for getting back to this issue!

Unfortunately, I still can reproduce it with the example from my previous comment and rust version 1.43.0-nightly (4ad624882 2020-03-03):
image.
You can check the example repo for additional details and screenshots.

Same happens at docs.rs for heim crate: https://docs.rs/heim/0.1.0-alpha.1/heim/cpu/struct.CpuFrequency.html; I would expect to see Frequency type alias instead of Quantity<dyn Dimension<M = Z0, I = Z0, N = Z0, .. as it is shown right now.

@ehuss ehuss removed the T-dev-tools Relevant to the dev-tools subteam, which will review and decide on the PR/issue. label Jan 18, 2022
@alice-i-cecile
Copy link

This is still an issue for me on rust 1.60.0-nightly.

@GuillaumeGomez
Copy link
Member

GuillaumeGomez commented Apr 4, 2022

It seems to be a tricky issue to fix. I opened rust-lang/compiler-team#504 so we'll see if it'll be able to fix this problem.

In the meantime, to add a test for this in rustdoc:

src/test/rustdoc/alias-reexport.rs

// aux-build:alias-reexport.rs
// aux-build:alias-reexport2.rs

#![crate_name = "foo"]

extern crate alias_reexport2;

// @has 'foo/reexport/fn.foo.html'
// @has - '//*[@class="docblock item-decl"]' 'pub fn foo() -> Reexport'
// @has 'foo/reexport/fn.foo2.html'
// @has - '//*[@class="docblock item-decl"]' 'pub fn foo2() -> Result<Reexport, ()>'
// @has 'foo/reexport/type.Reexported.html'
// @has - '//*[@class="docblock item-decl"]' 'pub type Reexported'
#[doc(inline)]
pub use alias_reexport2 as reexport;

src/test/rustdoc/alias-reexport2.rs

// aux-build:alias-reexport.rs

#![crate_name = "foo"]

extern crate alias_reexport;

use alias_reexport::Reexported;

// @has 'foo/fn.foo.html'
// @has - '//*[@class="docblock item-decl"]' 'pub fn foo() -> Reexported'
pub fn foo() -> Reexported { 0 }
// @has 'foo/fn.foo2.html'
// @has - '//*[@class="docblock item-decl"]' 'pub fn foo2() -> Result<Reexported, ()>'
pub fn foo2() -> Result<Reexported, ()> { Ok(0) }

src/test/rustdoc/auxiliary/alias-reexport.rs

pub type Reexported = u8;

src/test/rustdoc/auxiliary/alias-reexport2.rs

extern crate alias_reexport;

pub use alias_reexport::Reexported;

// @has 'foo/fn.foo.html'
// @has - '//*[@class="docblock item-decl"]' 'pub fn foo() -> Reexported'
pub fn foo() -> Reexported { 0 }
// @has 'foo/fn.foo2.html'
// @has - '//*[@class="docblock item-decl"]' 'pub fn foo2() -> Result<Reexported, ()>'
pub fn foo2() -> Result<Reexported, ()> { Ok(0) }

ConnorGray added a commit to WolframResearch/wstp-rs that referenced this issue Jan 6, 2023
The code mistakenly assumed that c_char was i8 on all Rust platforms, but
that is not true on Linux, so this is causing type mismatch errors at build
time on Linux.

(This mistake of mine was presumably reinforced by Rust issue #15823, which is
an issue with rustdoc rendering some type aliases in function signatures as
the pointed-to type and not by the alias name, which--among other effects--causes
CStr::from_raw() and CString::into_raw() to show `i8` in their type signatures
instead of `c_char`.)

See also: rust-lang/rust#15823
ConnorGray added a commit to WolframResearch/wstp-rs that referenced this issue Jan 6, 2023
…ux (#45)

The code mistakenly assumed that c_char was i8 on all Rust platforms, but
that is not true on Linux, so this is causing type mismatch errors at build
time on Linux.

(This mistake of mine was presumably reinforced by Rust issue #15823, which is
an issue with rustdoc rendering some type aliases in function signatures as
the pointed-to type and not by the alias name, which--among other effects--causes
CStr::from_raw() and CString::into_raw() to show `i8` in their type signatures
instead of `c_char`.)

See also: rust-lang/rust#15823
matthiaskrgr pushed a commit to matthiaskrgr/rust that referenced this issue Feb 20, 2023
matthiaskrgr added a commit to matthiaskrgr/rust that referenced this issue Feb 20, 2023
Document that CStr::as_ptr returns a type alias

Rustdoc resolves type aliases too eagerly rust-lang#15823 which makes the [std re-export](https://doc.rust-lang.org/stable/std/ffi/struct.CStr.html#method.as_ptr) of `CStr::as_ptr` show `i8` instead of `c_char`. To work around this I've added info about `c_char` in the method's description.

BTW, I've also added a comment to what-not-to-do example in case someone copypasted it without reading the surrounding text.
matthiaskrgr added a commit to matthiaskrgr/rust that referenced this issue Feb 20, 2023
Document that CStr::as_ptr returns a type alias

Rustdoc resolves type aliases too eagerly rust-lang#15823 which makes the [std re-export](https://doc.rust-lang.org/stable/std/ffi/struct.CStr.html#method.as_ptr) of `CStr::as_ptr` show `i8` instead of `c_char`. To work around this I've added info about `c_char` in the method's description.

BTW, I've also added a comment to what-not-to-do example in case someone copypasted it without reading the surrounding text.
@GuillaumeGomez
Copy link
Member

#112853 allowed to make a great step forward into fixing this issue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
C-bug Category: This is a bug. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

No branches or pull requests

10 participants