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

Many From implementations are undocumented #51430 #51738

Closed
wants to merge 1 commit into from
Closed

Many From implementations are undocumented #51430 #51738

wants to merge 1 commit into from

Conversation

sehinde-gb
Copy link

Hi, @skade This is my first pull request (Please be gentle with me....). I have followed your instructions, there could be a few mistakes. Let me know what they are and I will improve upon them.

@rust-highfive
Copy link
Collaborator

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @bluss (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

@rust-highfive rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jun 23, 2018
@rust-highfive
Copy link
Collaborator

The job x86_64-gnu-llvm-3.9 of your PR failed on Travis (raw log). Through arcane magic we have determined that the following fragments from the build log may contain information about the problem.

Click to expand the log.
[00:03:28]    Compiling rustc_msan v0.0.0 (file:///checkout/src/librustc_msan)
[00:03:41]    Compiling libc v0.0.0 (file:///checkout/src/rustc/libc_shim)
[00:03:41]    Compiling alloc v0.0.0 (file:///checkout/src/liballoc)
[00:03:41]    Compiling std_unicode v0.0.0 (file:///checkout/src/libstd_unicode)
[00:03:41] error: expected one of `const`, `crate`, `default`, `extern`, `fn`, `pub`, `type`, or `unsafe`, found `}`
[00:03:41]    --> liballoc/boxed.rs:431:1
[00:03:41]     |
[00:03:41] 429 |     /// This conversion is more expensive because the <T> is not already on the heap.
[00:03:41]     |                                                                                      - expected one of 8 possible tokens here
[00:03:41] 431 | }
[00:03:41] 431 | }
[00:03:41]     | ^ unexpected token
[00:03:41] 
[00:03:41] error: expected one of `const`, `crate`, `default`, `extern`, `fn`, `pub`, `type`, or `unsafe`, found `}`
[00:03:41]    --> liballoc/boxed.rs:448:1
[00:03:41]     |
[00:03:41] 446 |     /// and the pointer moves along
[00:03:41]     |                                    - expected one of 8 possible tokens here
[00:03:41] 448 | }
[00:03:41] 448 | }
[00:03:41]     | ^ unexpected token
[00:03:41] 
[00:03:41] error: expected one of `const`, `crate`, `default`, `extern`, `fn`, `pub`, `type`, or `unsafe`, found `}`
[00:03:41]    --> liballoc/boxed.rs:466:1
[00:03:41] 463 |     /// on the heap.
[00:03:41] 463 |     /// on the heap.
[00:03:41]     |                     - expected one of 8 possible tokens here
[00:03:41] 466 | }
[00:03:41] 466 | }
[00:03:41]     | ^ unexpected token
[00:03:41] 
[00:03:41] error: expected one of `const`, `crate`, `default`, `extern`, `fn`, `pub`, `type`, or `unsafe`, found `}`
[00:03:41]    --> liballoc/boxed.rs:482:1
[00:03:41]     |
[00:03:41] 481 |     /// This function is unsafe. Data can't be moved from this reference.
[00:03:41]     |                                                                          - expected one of 8 possible tokens here
[00:03:41] 482 | }
[00:03:41]     | ^ unexpected token
[00:03:41] 
[00:03:41] error: expected one of `const`, `crate`, `default`, `extern`, `fn`, `pub`, `type`, or `unsafe`, found `}`
[00:03:41]    --> liballoc/boxed.rs:904:1
[00:03:41] 903 |     /// heap.
[00:03:41] 903 |     /// heap.
[00:03:41]     |              - expected one of 8 possible tokens here
[00:03:41] 904 | }
[00:03:41]     | ^ unexpected token
[00:03:41] 
[00:03:41] error: expected one of `const`, `crate`, `default`, `extern`, `fn`, `pub`, `type`, or `unsafe`, found `}`
[00:03:41]    --> liballoc/boxed.rs:916:1
[00:03:41] 915 |     /// heap.
[00:03:41] 915 |     /// heap.
[00:03:41]     |              - expected one of 8 possible tokens here
[00:03:41] 916 | }
[00:03:41]     | ^ unexpected token
[00:03:41] 
[00:03:41] error: expected one of `const`, `crate`, `default`, `extern`, `fn`, `pub`, `type`, or `unsafe`, found `}`
[00:03:41]     --> liballoc/boxed.rs:1012:1
[00:03:41]      |
[00:03:41] 1010 |     /// This conversion is cheaper because the PinBox is already on the heap.
[00:03:41]      |                                                                              - expected one of 8 possible tokens here
[00:03:41] 1012 | }
[00:03:41] 1012 | }
[00:03:41]      | ^ unexpected token
[00:03:41] 
[00:03:41] error: expected one of `const`, `crate`, `default`, `extern`, `fn`, `pub`, `type`, or `unsafe`, found `}`
[00:03:41]     --> liballoc/boxed.rs:1024:1
[00:03:41]      |
[00:03:41] 1022 |     /// This conversion is cheaper because the Box is already on the heap.
[00:03:41]      |                                                                           - expected one of 8 possible tokens here
[00:03:41] 1024 | }
[00:03:41] 1024 | }
[00:03:41]      | ^ unexpected token
[00:03:42]    Compiling alloc_system v0.0.0 (file:///checkout/src/liballoc_system)
[00:03:42]    Compiling panic_abort v0.0.0 (file:///checkout/src/libpanic_abort)
[00:03:43] error: aborting due to 8 previous errors
[00:03:43] 
[00:03:43] 
[00:03:43] error: Could not compile `alloc`.
[00:03:43] 
[00:03:43] Caused by:
[00:03:43]   process didn't exit successfully: `/checkout/obj/build/bootstrap/debug/rustc --crate-name alloc liballoc/lib.rs --color always --error-format json --crate-type lib --emit=dep-info,link -C opt-level=2 -C metadata=d6cd5f8b78fddf12 -C extra-filename=-d6cd5f8b78fddf12 --out-dir /checkout/obj/build/x86_64-unknown-linux-gnu/stage0-std/x86_64-unknown-linux-gnu/release/deps --target x86_64-unknown-linux-gnu -L dependency=/checkout/obj/build/x86_64-unknown-linux-gnu/stage0-std/x86_64-unknown-linux-gnu/release/deps -L dependency=/checkout/obj/build/x86_64-unknown-linux-gnu/stage0-std/release/deps --extern core=/checkout/obj/build/x86_64-unknown-linux-gnu/stage0-std/x86_64-unknown-linux-gnu/release/deps/libcore-e9cdce497aae9e81.rlib --extern compiler_builtins=/checkout/obj/build/x86_64-unknown-linux-gnu/stage0-std/x86_64-unknown-linux-gnu/release/deps/libcompiler_builtins-90a13cda2e54742f.rlib -L native=/checkout/obj/build/x86_64-unknown-linux-gnu/stage0-std/x86_64-unknown-linux-gnu/release/build/compiler_builtins-ffd422941bf53e42/out` (exit code: 101)
[00:03:43] command did not execute successfully: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0/bin/cargo" "build" "--target" "x86_64-unknown-linux-gnu" "-j" "4" "--release" "--locked" "--color" "always" "--features" "panic-unwind jemalloc backtrace" "--manifest-path" "/checkout/src/libstd/Cargo.toml" "--message-format" "json"
[00:03:43] expected success, got: exit code: 101
[00:03:43] thread 'main' panicked at 'cargo must succeed', bootstrap/compile.rs:1091:9
[00:03:43] travis_fold:end:stage0-std

[00:03:43] travis_time:end:stage0-std:start=1529773670313722367,finish=1529773700848827912,duration=30535105545


[00:03:43] failed to run: /checkout/obj/build/bootstrap/debug/bootstrap test src/tools/tidy
[00:03:43] Build completed unsuccessfully in 0:00:31
[00:03:43] Makefile:79: recipe for target 'tidy' failed
[00:03:43] make: *** [tidy] Error 1

The command "stamp sh -x -c "$RUN_SCRIPT"" exited with 2.
travis_time:start:0db9de90
$ date && (curl -fs --head https://google.com | grep ^Date: | sed 's/Date: //g' || true)
---
travis_time:end:00124c06:start=1529773701354458889,finish=1529773701362190494,duration=7731605
travis_fold:end:after_failure.3
travis_fold:start:after_failure.4
travis_time:start:003dbd86
$ head -30 ./obj/build/x86_64-unknown-linux-gnu/native/asan/build/lib/asan/clang_rt.asan-dynamic-i386.vers || true
head: cannot open ‘./obj/build/x86_64-unknown-linux-gnu/native/asan/build/lib/asan/clang_rt.asan-dynamic-i386.vers’ for reading: No such file or directory
travis_fold:end:after_failure.4
travis_fold:start:after_failure.5
travis_time:start:089aadc4
$ dmesg | grep -i kill

I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact @TimNN. (Feature Requests)

@clarfonthey
Copy link
Contributor

clarfonthey commented Jun 23, 2018

I appreciate the effort to document these conversions! I think that right now the way rustdoc works, it's kind of hard to actually see the documentation for these. The docs for From are extremely long and most of the impls are drowned out by the conversions between integers.

I think that adding docs on the impls themselves is a good thing, although maybe it might be better for some of these to put them elsewhere so they're also seen. For example, the impl for Future could go in the docs for Future, and the docs for converting between &str and Box<str> could go on str's docs. Some of these end up just calling existing methods and could go alongside the docs for those methods.

Actually figuring out how to make these docs easy to find is a difficult problem, so, I think that modifying what you've got so far is definitely fine for now. Congrats on your first pull request. :)

@skade
Copy link
Contributor

skade commented Jun 24, 2018

Hi @clarcharr, I think #51430 is the better place for that kind of feedback.

Rustdoc drowning From implementations is an issue but IMHO not in scope for this.

@stokhos stokhos 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-review Status: Awaiting review from the assignee but also interested parties. labels Jun 29, 2018
@bors
Copy link
Contributor

bors commented Jul 2, 2018

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

@pietroalbini
Copy link
Member

Thanks for this PR @ormrepo! The build is failing, and there are conflicts that needs to be solved. Do you have time to fix those?

@sehinde-gb
Copy link
Author

sehinde-gb commented Jul 9, 2018 via email

@pietroalbini
Copy link
Member

@ormrepo don't worry, I'm just checking in to make sure PRs are not abandoned :)

@TimNN
Copy link
Contributor

TimNN commented Jul 17, 2018

Ping from triage, @skade! This PR is waiting for your review! Also cc @rust-lang/docs in case @skade is unavailable in the near future.

@TimNN TimNN added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Jul 17, 2018
@pietroalbini
Copy link
Member

Ping from triage @skade @rust-lang/docs, this PR needs your review.

@pietroalbini pietroalbini added I-nominated A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools labels Jul 30, 2018
@pietroalbini
Copy link
Member

Ping from triage! This PR needs a review, can @skade or someone else from @rust-lang/docs review this?

@alercah
Copy link
Contributor

alercah commented Jul 31, 2018

Won't the conversions also show up on the types with the From impls, and not only on the trait page?

@@ -414,38 +414,74 @@ impl<T: ?Sized + Hasher> Hasher for Box<T> {
}
}

/// First From
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not a fan of this type of comment in general, but especially not as a doc comment. This won't make much sense to appear in the generated documentation.

In code, these sorts of comments are possibly useful for navigation, but they are subject to bitrot and I think that they are consequently not that valuable.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed

/// Converts a T into a Box.
/// This conversion does allocate memory.
/// This conversion is not free.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Redundant blank line.

/// Copies a T in to a box.
/// This conversion copies the data.
/// This conversion does allocate memory.
///
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Extraneous blank line.

fn from(slice: &'a [T]) -> Box<[T]> {
let mut boxed = unsafe { RawVec::with_capacity(slice.len()).into_box() };
boxed.copy_from_slice(slice);
boxed
}
/// The result is allocated on the heap
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doc comment doesn't apply to anything. There are a number of these and they should be incorporated into the actual docs or removed. If you think there is value to leaving explanatory comments in the code, I think that they should be a separate PR so that libs team can evaluate them.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed.

@sehinde-gb
Copy link
Author

sehinde-gb commented Jul 31, 2018 via email

Copy link
Author

@sehinde-gb sehinde-gb left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks Steve for the clarification. And I agree with you. I don't have permission to approve these changes. I am a newbie here. Can someone please approve these changes and close down the PR request ? Or is this PR request owned by @skade I haven't heard from him in nearly 6 weeks.......

@Mark-Simulacrum
Copy link
Member

I'm assigning @steveklabnik as the reviewer here. I believe the next step is to rebase and fix the comments left by @alercah and @steveklabnik.

r? @steveklabnik

@rust-highfive rust-highfive assigned steveklabnik and unassigned bluss Jul 31, 2018
@TimNN TimNN 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-review Status: Awaiting review from the assignee but also interested parties. labels Aug 14, 2018
@TimNN
Copy link
Contributor

TimNN commented Aug 14, 2018

Ping from triage, @ormrepo. It looks like some changes have been requested to your PR.

@sehinde-gb
Copy link
Author

sehinde-gb commented Aug 15, 2018 via email

@TimNN
Copy link
Contributor

TimNN commented Aug 15, 2018

Thank you for contributing to the Rust project, @ormrepo. Please note that this Pull Request cannot be approved right now. Reviewers have requested some changes, which you need to make before approval can be granted. (Note that @skade does not necessarily have to be involved in the process if they are unreachable at the moment. Others, like @steveklabnik, can also approve this PR once the requested changes have been made).


To make the requested changes, you'll have to go to your local checkout of the boxrs_edits branch, make the requested changes, and then finally commit and push them to GitHub.


Edit: I forgot to mention: after making you changes, you'll also need to rebase you branch.

How do I rebase?


Copied from one of @bors' comments.

Assuming self is your fork and upstream is this repository, you can resolve the conflict following these steps:

  1. git checkout boxrs_edits (switch to your branch)
  2. git fetch upstream master (retrieve the latest master)
  3. git rebase upstream/master -p (rebase on top of it)
  4. Follow the on-screen instruction to resolve conflicts (check git status if you got lost).
  5. git push self boxrs_edits --force-with-lease (update this PR)

You may also read Git Rebasing to Resolve Conflicts by Drew Blessing for a short tutorial.

Please avoid the "Resolve conflicts" button on GitHub. It uses git merge instead of git rebase which makes the PR commit history more difficult to read.

Sometimes step 4 will complete without asking for resolution. This is usually due to difference between how Cargo.lock conflict is handled during merge and rebase. This is normal, and you should still perform step 5 to update this PR.

@sehinde-gb
Copy link
Author

sehinde-gb commented Aug 15, 2018 via email

@TimNN
Copy link
Contributor

TimNN commented Aug 15, 2018

You can see your defined remotes by running git remote -v. You're interested in the one associated with github.com:ormrepo/rust.git.

If you don't have one, you can use one of these commands to set one up:

git remote add upstream git@github.com:ormrepo/rust.git
# Or, if you don't have ssh set up
git remote add upstream https://github.com/ormrepo/rust.git

@pietroalbini
Copy link
Member

Ping from triage @ormrepo! It's been a while since we heard from you, will you have time to work on this again?

@TimNN
Copy link
Contributor

TimNN commented Sep 4, 2018

Ping from triage @ormrepo: We haven't heard from you in a while so I'm closing this PR as per our triage guidelines. Thank you for your contribution and please re-open this PR (or a new one) when you are able to work on this PR again.

@TimNN TimNN closed this Sep 4, 2018
@TimNN TimNN added S-inactive Status: Inactive and waiting on the author. This is often applied to closed PRs. and removed I-nominated S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Sep 4, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools S-inactive Status: Inactive and waiting on the author. This is often applied to closed PRs.
Projects
None yet
Development

Successfully merging this pull request may close these issues.