Enable API documentation for `std::os::wasi`. by sunfishcode · Pull Request #82420 · rust-lang/rust

sunfishcode · 2021-02-22T22:31:06Z

This adds API documentation support for std::os::wasi modeled after
how std::os::unix works, so that WASI can be documented here along
with the other platforms.

Two changes of particular interest:

This changes the AsRawFd for io::Stdin for WASI to return
libc::STDIN_FILENO instead of sys::stdio::Stdin.as_raw_fd() (and
similar for Stdout and Stderr), which matches how the unix
version works. STDIN_FILENO etc. may not always be explicitly
reserved at the WASI level, but as long as we have Rust's std and
libc, I think it's reasonable to guarantee that we'll always use
libc::STDIN_FILENO for stdin.
This duplicates the osstr2str utility function, rather than
trying to share it across all the configurations that need it.

r? @alexcrichton

alexcrichton · 2021-02-22T22:56:02Z

@bors: r+

bors · 2021-02-22T22:56:04Z

📌 Commit 643d2ce3e2de481593bc4aaee81f1df361680864 has been approved by alexcrichton

library/std/src/os/mod.rs

bors · 2021-02-23T07:49:19Z

☔ The latest upstream changes (presumably #82430) made this pull request unmergeable. Please resolve the merge conflicts.

This adds API documentation support for `std::os::wasi` modeled after how `std::os::unix` works, so that WASI can be documented [here] along with the other platforms. [here]: https://doc.rust-lang.org/stable/std/os/index.html Two changes of particular interest: - This changes the `AsRawFd` for `io::Stdin` for WASI to return `libc::STDIN_FILENO` instead of `sys::stdio::Stdin.as_raw_fd()` (and similar for `Stdout` and `Stderr`), which matches how the `unix` version works. `STDIN_FILENO` etc. may not always be explicitly reserved at the WASI level, but as long as we have Rust's `std` and `libc`, I think it's reasonable to guarantee that we'll always use `libc::STDIN_FILENO` for stdin. - This duplicates the `osstr2str` utility function, rather than trying to share it across all the configurations that need it.

alexcrichton · 2021-02-23T15:19:25Z

@bors: r+ delegate+

bors · 2021-02-23T15:19:26Z

📌 Commit 132ec26 has been approved by alexcrichton

bors · 2021-02-23T15:19:28Z

✌️ @sunfishcode can now approve this pull request

library/std/src/sys/mod.rs

CDirkx · 2021-02-23T21:09:15Z

Currently the documentation does not build for all platforms:

rust/library/std/src/sys/wasi/ext/mod.rs

Lines 11 to 24 in fe1bf8e

    
           pub mod prelude { 
        
               #[doc(no_inline)] 
        
               #[stable(feature = "rust1", since = "1.0.0")] 
        
               pub use crate::sys::ext::ffi::{OsStrExt, OsStringExt}; 
        
               #[doc(no_inline)] 
        
               #[stable(feature = "rust1", since = "1.0.0")] 
        
               pub use crate::sys::ext::fs::FileTypeExt; 
        
               #[doc(no_inline)] 
        
               #[stable(feature = "rust1", since = "1.0.0")] 
        
               pub use crate::sys::ext::fs::{DirEntryExt, FileExt, MetadataExt, OpenOptionsExt}; 
        
               #[doc(no_inline)] 
        
               #[stable(feature = "rust1", since = "1.0.0")] 
        
               pub use crate::sys::ext::io::{AsRawFd, FromRawFd, IntoRawFd, RawFd}; 
        
           }

All these should use super:: instead of crate::sys::ext because with this change, when documenting on windows for example, sys::ext will be the windows ext, not the wasi one.

Also, technically if one would ever document targeting wasi (not currently possible I think) the module os::wasi would be defined twice because of the missing #[cfg(not(doc))]:

rust/library/std/src/os/mod.rs

Lines 71 to 72 in fe1bf8e

    
           #[cfg(target_os = "wasi")] 
        
           pub mod wasi;

and now wasi can also be added to the comment at the top of os/mod.rs:

rust/library/std/src/os/mod.rs

Line 6 in fe1bf8e

    
           // When documenting libstd we want to show unix/windows/linux modules as these are the "main

CDirkx · 2021-02-23T21:26:19Z

Rustdoc will also need to be updated, but that can be a followup.

Enable API documentation for `std::os::wasi`. This adds API documentation support for `std::os::wasi` modeled after how `std::os::unix` works, so that WASI can be documented [here] along with the other platforms. [here]: https://doc.rust-lang.org/stable/std/os/index.html Two changes of particular interest: - This changes the `AsRawFd` for `io::Stdin` for WASI to return `libc::STDIN_FILENO` instead of `sys::stdio::Stdin.as_raw_fd()` (and similar for `Stdout` and `Stderr`), which matches how the `unix` version works. `STDIN_FILENO` etc. may not always be explicitly reserved at the WASI level, but as long as we have Rust's `std` and `libc`, I think it's reasonable to guarantee that we'll always use `libc::STDIN_FILENO` for stdin. - This duplicates the `osstr2str` utility function, rather than trying to share it across all the configurations that need it. r? `@alexcrichton`

Enable API documentation for `std::os::wasi`. This adds API documentation support for `std::os::wasi` modeled after how `std::os::unix` works, so that WASI can be documented [here] along with the other platforms. [here]: https://doc.rust-lang.org/stable/std/os/index.html Two changes of particular interest: - This changes the `AsRawFd` for `io::Stdin` for WASI to return `libc::STDIN_FILENO` instead of `sys::stdio::Stdin.as_raw_fd()` (and similar for `Stdout` and `Stderr`), which matches how the `unix` version works. `STDIN_FILENO` etc. may not always be explicitly reserved at the WASI level, but as long as we have Rust's `std` and `libc`, I think it's reasonable to guarantee that we'll always use `libc::STDIN_FILENO` for stdin. - This duplicates the `osstr2str` utility function, rather than trying to share it across all the configurations that need it. r? ``@alexcrichton``

JohnTitor · 2021-02-24T14:51:11Z

Failed in rollup: #82472 (comment)
@bors r-

WASI's `RawFd` is a `u32`, while `libc` uses `c_int`.

This ensures that these names resolve to the right place even when building the WASI support on other platforms for generating the documentation.

sunfishcode · 2021-02-24T18:48:32Z

Thanks! I've now fixed the crate::sys::ext paths, added the cfg(not(doc)) to the main wasi module, and added "wasi" to the "main module" comment.

alexcrichton · 2021-02-25T17:42:17Z

@bors: r+

bors · 2021-02-25T17:42:18Z

📌 Commit 7d5242a has been approved by alexcrichton

Enable API documentation for `std::os::wasi`. This adds API documentation support for `std::os::wasi` modeled after how `std::os::unix` works, so that WASI can be documented [here] along with the other platforms. [here]: https://doc.rust-lang.org/stable/std/os/index.html Two changes of particular interest: - This changes the `AsRawFd` for `io::Stdin` for WASI to return `libc::STDIN_FILENO` instead of `sys::stdio::Stdin.as_raw_fd()` (and similar for `Stdout` and `Stderr`), which matches how the `unix` version works. `STDIN_FILENO` etc. may not always be explicitly reserved at the WASI level, but as long as we have Rust's `std` and `libc`, I think it's reasonable to guarantee that we'll always use `libc::STDIN_FILENO` for stdin. - This duplicates the `osstr2str` utility function, rather than trying to share it across all the configurations that need it. r? `@alexcrichton`

Enable API documentation for `std::os::wasi`. This adds API documentation support for `std::os::wasi` modeled after how `std::os::unix` works, so that WASI can be documented [here] along with the other platforms. [here]: https://doc.rust-lang.org/stable/std/os/index.html Two changes of particular interest: - This changes the `AsRawFd` for `io::Stdin` for WASI to return `libc::STDIN_FILENO` instead of `sys::stdio::Stdin.as_raw_fd()` (and similar for `Stdout` and `Stderr`), which matches how the `unix` version works. `STDIN_FILENO` etc. may not always be explicitly reserved at the WASI level, but as long as we have Rust's `std` and `libc`, I think it's reasonable to guarantee that we'll always use `libc::STDIN_FILENO` for stdin. - This duplicates the `osstr2str` utility function, rather than trying to share it across all the configurations that need it. r? ``@alexcrichton``

Rollup of 14 pull requests Successful merges: - rust-lang#81794 (update tracking issue for `relaxed_struct_unsize`) - rust-lang#82057 (Replace const_cstr with cstr crate) - rust-lang#82370 (Improve anonymous lifetime note to indicate the target span) - rust-lang#82394 (:arrow_up: rust-analyzer) - rust-lang#82396 (Add Future trait for doc_spotlight feature doc) - rust-lang#82404 (Test hexagon-enum only when llvm target is present) - rust-lang#82419 (expand: Preserve order of inert attributes during expansion) - rust-lang#82420 (Enable API documentation for `std::os::wasi`.) - rust-lang#82421 (Add a `size()` function to WASI's `MetadataExt`.) - rust-lang#82442 (Skip emitting closure diagnostic when closure_kind_origins has no entry) - rust-lang#82473 (Use libc::accept4 on Android instead of raw syscall.) - rust-lang#82482 (Use small hash set in `mir_inliner_callees`) - rust-lang#82490 (Update cargo) - rust-lang#82494 (Substitute erased lifetimes on bad placeholder type) Failed merges: - rust-lang#82448 (Combine HasAttrs and HasTokens into AstLike) r? `@ghost` `@rustbot` modify labels: rollup

As a followup to [this comment] in rust-lang#82420, this patch teaches rustdoc how to display WASI. [this comment]: rust-lang#82420 (comment)

Teach rustdoc how to display WASI. As a followup to [this comment] in rust-lang#82420, this patch teaches rustdoc how to display WASI. [this comment]: rust-lang#82420 (comment) r? `@alexcrichton`

rust-highfive assigned alexcrichton Feb 22, 2021

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Feb 22, 2021

alexcrichton approved these changes Feb 22, 2021

View reviewed changes

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Feb 22, 2021

camelid reviewed Feb 23, 2021

View reviewed changes

library/std/src/os/mod.rs Outdated Show resolved Hide resolved

camelid added O-wasm Target: WASM (WebAssembly), http://webassembly.org/ A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools T-libs-api Relevant to the library API team, which will review and decide on the PR/issue. labels Feb 23, 2021

bors added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels Feb 23, 2021

sunfishcode force-pushed the wasi-docs branch from 643d2ce to 5c46468 Compare February 23, 2021 13:31

This comment has been minimized.

Sign in to view

sunfishcode force-pushed the wasi-docs branch from 5c46468 to 132ec26 Compare February 23, 2021 13:40

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Feb 23, 2021

CDirkx reviewed Feb 23, 2021

View reviewed changes

library/std/src/sys/mod.rs Show resolved Hide resolved

Dylan-DPC-zz mentioned this pull request Feb 24, 2021

Rollup of 14 pull requests #82458

Closed

Dylan-DPC-zz mentioned this pull request Feb 24, 2021

Rollup of 14 pull requests #82460

Closed

bors added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels Feb 24, 2021

sunfishcode added 4 commits February 24, 2021 10:35

Cast libc::STDIN_FILENO to RawFd.

9ce567e

WASI's `RawFd` is a `u32`, while `libc` uses `c_int`.

Use super:: to refer to WASI-specific names.

0208fca

This ensures that these names resolve to the right place even when building the WASI support on other platforms for generating the documentation.

Make the main wasi module cfg(not(doc)).

e66e263

Mention "wasi" in the comment about "main modules".

94e75ac

x.py fmt

7d5242a

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Feb 25, 2021

Dylan-DPC-zz mentioned this pull request Feb 26, 2021

Rollup of 9 pull requests #82538

Closed

Dylan-DPC-zz mentioned this pull request Feb 27, 2021

Rollup of 11 pull requests #82574

Closed

Dylan-DPC-zz mentioned this pull request Feb 27, 2021

Rollup of 14 pull requests #82577

Merged

bors merged commit f5b68a4 into rust-lang:master Feb 27, 2021

rustbot added this to the 1.52.0 milestone Feb 27, 2021

sunfishcode deleted the wasi-docs branch February 27, 2021 15:30

sunfishcode added a commit to sunfishcode/rust that referenced this pull request Feb 27, 2021

Teach rustdoc how to display WASI.

b89e828

As a followup to [this comment] in rust-lang#82420, this patch teaches rustdoc how to display WASI. [this comment]: rust-lang#82420 (comment)

sunfishcode mentioned this pull request Feb 27, 2021

Teach rustdoc how to display WASI. #82593

Merged

camelid mentioned this pull request Feb 27, 2021

Check stability and feature attributes in rustdoc #82598

Merged

Uh oh!

Conversation

sunfishcode commented Feb 22, 2021

Uh oh!

alexcrichton commented Feb 22, 2021

Uh oh!

bors commented Feb 22, 2021

Uh oh!

Uh oh!

bors commented Feb 23, 2021

Uh oh!

This comment has been minimized.

alexcrichton commented Feb 23, 2021

Uh oh!

bors commented Feb 23, 2021

Uh oh!

bors commented Feb 23, 2021

Uh oh!

Uh oh!

CDirkx commented Feb 23, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

CDirkx commented Feb 23, 2021

Uh oh!

JohnTitor commented Feb 24, 2021

Uh oh!

sunfishcode commented Feb 24, 2021

Uh oh!

alexcrichton commented Feb 25, 2021

Uh oh!

bors commented Feb 25, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

CDirkx commented Feb 23, 2021 •

edited

Loading