Doc: Clarify the meaning of "copy" in std::mem::swap/replace

[jrgold]

The use of "without copying" in the std::mem docs was a source of confusion to those less familiar with Rust, as it could refer to either semantic copying or byte copying. This clarifies which meaning was intended.

[rust-highfive]

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

[Gankra]

A shallow byte-level copy is what a Copy is, no? I think this might be more confusing.

[jrgold]

I guess it is a bit confusing, as Copy is for shallow byte copy-able types. I was trying to use the terminology used in this reddit thread: http://redd.it/2j1vqa. /u/dbaupp talks about the distinction in their comment. I'll have a think about a way to succinctly clarify the distinction.

[Gankra]

CC @huonw are you happy with this wording going into the docs?

[reem]

How about without cloning either one. We use clone to mean semantic copy elsewhere and in regular discussion.

[jrgold]

Using clone instead of semantic copy sounds like a good solution to me - it removes the confusion over the meaning of "copy".

[pnkfelix]

(I'd say "without recursively copying" myself, rather than "without semantically copying". I don't know why I prefer the former over "clone" ... maybe I need to see more of the spots that @reem is referring to; I usually think of clone as talking specifically about the method on the Clone trait.)

[jrgold]

Are there ways to recursively copy other than by using clone? If not, I'd say it makes sense to include clone for consistency's sake. "Recursively copy" instead of "semantically copying" sounds like a good change to me either way.

[reem]

Since we attach "semantic copy" to the Clone trait, I think it's an appropriate use of the term.

You could say that this "swaps the values at two memory locations without dropping either one, using only shallow copies."

[huonw]

FWIW, "semantic copy" is just terminology I have been using to describe the difference (the first time I know it was used was this SO answer of mine), it's not really attached to Clone. Of course, we can always connect that name to Clone.

To be clear, I'm very happy with using the terminology in the docs, but I'm also happy with "clone" or "recursively copying".

[jrgold]

Alright I've updated the wording of the changed documentation with everyone's suggestions. I think I may have done something wrong in the process of committing/pulling though, so I apologize if I've made anything difficult for anyone, I'm totally new to git and github.

[alexcrichton]

@jrgold looks like this picked up a lot of extra commits, you may want to do something like this to start over:

git checkout doc-mem-copy-meaning
git reset --hard origin/master
git cherry-pick 847ed00
git cherry-pick 7fe313b

[Gankra]

@jrgold what's your status?

[jrgold]

Sorry, I've been really caught up with final exams these past few weeks, and I didn't want to risk doing something wrong here in case I didn't have the time to fix it.

I've taken the steps @alexcrichton listed on my local copy. I'm unsure as to what other steps I need to take before pushing again; the development policy note talks about rebasing against master, but I'm not sure if that's only for the initial push before I made the pull request (I think I mucked this up before, which is what pulled in all those extra commits).

[Gankra]

If it's been a while, it's good policy to rebase against master in case someone's come by and changed things since. But this is up to your discretion as long as everything merges and checks.

[steveklabnik]

Yes, this will not merge without being rebased.

[alexcrichton]

Closing due to inactivity (and @bors's queue is quite full!). Feel free to reopen with a rebase!