Discourage overuse of mem::forget

[kornelski]

Some uses of mem::forget have been replaced by better methods of Box, so I've removed obsoleted use-cases from these docs.

I've removed emphasis on leaking, because it's not obvious mem::forget does not guarantee leaking of memory: memory of stack-allocated objects and values partially moved out of Box will still be freed. That's a potential error when used to pass objects to FFI, so it's better to direct users to Box::into_raw instead.

[rust-highfive]

r? @dtolnay

(rust_highfive has picked a reviewer for you, use r? to override)

[dtolnay]

@bors r+ rollup

[bors]

📌 Commit 2fae6e2ae114cd9e7dc1a1d4e415eab57c19ca3e has been approved by dtolnay

[rust-highfive]

The job x86_64-gnu-llvm-5.0 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:44:35] ....................................................................................................
[00:44:37] ....................................................................................................
[00:44:40] ....................................................................................................
[00:44:44] ........i...........................................................................................
[00:44:48] ..................................................................................F...........i.....
[00:44:51] ..i.................................................................................................
[00:44:56] ....................................................................................................
[00:44:58] ....................................................................................................
[00:45:01] ....................................................................................................
[00:45:03] ....................................................................................................
---
[00:46:12] ....................................................................................................
[00:46:16] .......................................i............................................................
[00:46:19] ....................................................................................................
[00:46:22] ....................................................................................................
":[{"file_name":"/checkout/src/test/ui/consts/const-size_of-cycle.rs","byte_start":0,"byte_end":0,"line_start":1,"line_end":1,"column_start":1,"column_end":1,"is_primary":true,"text":[{"text":"// Copyright 2017 The Rust Project Developers. See the COPYRIGHT","highlight_start":1,"highlight_end":1}],"label":null,"suggested_replacement":null,"suggestion_applicability":null,"expansion":null}],"children":[{"message":"...which requires normalizing `ParamEnvAnd { param_env: ParamEnv { caller_bounds: [], reveal: All }, value: [u8; _] }`...","code":null,"level":"note","spans":[{"file_name":"/checkout/src/test/ui/consts/const-size_of-cycle.rs","byte_start":0,"byte_end":0,"line_start":1,"line_end":1,"column_start":1,"column_end":1,"is_primary":true,"text":[{"text":"// Copyright 2017 The Rust Project Developers. See the COPYRIGHT","highlight_start":1,"highlight_end":1}],"label":null,"suggested_replacement":null,"suggestion_applicability":null,"expansion":null}],"children":[],"rendered":null},{"message":"...which requires const-evaluating `Foo::bytes::{{constant}}`...","code":null,"level":"note","spans":[{"file_name":"/checkout/src/libcore/mem.rs","byte_start":9648,"byte_end":9674,"line_start":291,"line_end":291,"column_start":14,"column_end":40,"is_primary":true,"text":[{"text":"    unsafe { intrinsics::size_of::<T>() }","highlight_start":14,"highlight_end":40}],"label":null,"suggested_replacement":null,"suggestion_applicability":null,"expansion":null}],"children":[],"rendered":null},{"message":"...which again requires computing layout of `Foo`, completing the cycle","code":null,"level":"note","spans":[],"children":[],"rendered":null},{"

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)

[kornelski]

The build failure seems to be from unrelated commit.

[kennytm]

@bors r-

This PR caused UI test failure in #53530 (comment). That UI test contains some line numbers from libcore/mem.rs which this PR changed.

[dtolnay]

I filed #53547 to fix the brittle test. For now @kornelski 😭 it looks like you will need to find the new line number and update const-size_of-cycle.stderr in this PR. (Or fix #53547 yourself if you are up for it?)

[kornelski]

Fix for the other test is now merged. I've rebased this.

[dtolnay]

@bors r+ rollup

[bors]

📌 Commit e7709b3 has been approved by dtolnay