added toc entry and more edits

mikeblome · mikeblome · commit df5b1c7ba291 · 2019-12-05T16:15:32.000-08:00
diff --git a/docs/cpp/functions-cpp.md b/docs/cpp/functions-cpp.md
@@ -246,7 +246,7 @@ When **auto** is used in conjunction with a trailing return type, it just serves
 
 ## Function local variables
 
-A variable that is declared inside a function body is called a *local variable* or simply a *local*. Non-static locals are only visible inside the function body and, if they are declared on the stack go out of scope when the function exits. When you construct a local variable and return it by value, the compiler can usually perform the return value optimization to avoid unnecessary copy operations. If you return a local variable by reference, the compiler will issue a warning because any attempt by the caller to use that reference will occur after the local has been destroyed.
+A variable that is declared inside a function body is called a *local variable* or simply a *local*. Non-static locals are only visible inside the function body and, if they are declared on the stack go out of scope when the function exits. When you construct a local variable and return it by value, the compiler can usually perform the [named return value optimization](nrvo-cpp.md) to avoid unnecessary copy operations. If you return a local variable by reference, the compiler will issue a warning because any attempt by the caller to use that reference will occur after the local has been destroyed.
 
 In C++ a local variable may be declared as static. The variable is only visible inside the function body, but a single copy of the variable exists for all instances of the function. Local static objects are destroyed during termination specified by `atexit`. If a static object was not constructed because the program's flow of control bypassed its declaration, no attempt is made to destroy that object.
 
@@ -282,7 +282,6 @@ template<typename F, typename Tuple = tuple<T...>,
 {
     return apply_(std::forward<F>(f), std::forward<Tuple>(args), Indices());
 }
-}
 ```
 
 ## <a name="multi_val"></a> Returning multiple values from a function
diff --git a/docs/cpp/nrvo-cpp.md b/docs/cpp/nrvo-cpp.md
@@ -1,15 +1,23 @@
 ---
 title: "Named Return Value Optimization"
-ms.date: "11/19/2019"
+ms.date: "12/06/2019"
 description: "The named return value optimization (NRVO) in the Microsoft C++ compiler eliminates redundant copy constructor and destructor calls in various situations."
 helpviewer_keywords: ["NRVO [C++]", "Named return value optimization [C++]"]
 ---
 
 # Named Return Value Optimization
 
-The Microsoft C++ optimizing compiler uses various techniques to increase program performance whenever possible. One such technique is the named return value optimization (NRVO), which eliminates redundant copy constructor and destructor calls in various situations.
+The Microsoft C++ compiler uses various techniques to increase program performance whenever possible. One such technique is the named return value optimization (NRVO), which eliminates redundant copy constructor and destructor calls in various situations.
 
-Typically, when a function returns an instance of an object, the compiler invokes the class's copy constructor to create a temporary object, which it then copies to the target object. The C++ standard allows the elision of the copy constructor (even if this results in different program behavior).  which has a side effect of enabling the compiler to treat both objects as one (see section 12.8. Copying class objects, paragraph 15; see Reference*).* The Visual C++ 8.0 compiler makes use of the flexibility that the standard provides and adds a new feature: Named Return Value Optimization (NRVO). NRVO eliminates the copy constructor and destructor of a stack-based return value. This optimizes out the redundant copy constructor and destructor calls and thus improves overall performance. It is to be noted that this could lead to different behavior between optimized and non-optimized programs (see the Optimization Side Effects section).
+Consider what steps are required in a program, if no optimizations are enabled, when a function declares a local class variable on the stack and returns it to a caller:
+
+- construct the variable at the call site that will be assigned the returned object
+- construct the local variable of the same type
+- make a copy of the variable by invoking the copy constructor
+- assign the copy to the variable constructed at the call site
+- invoke the destructor for all three instances of the class when each goes out of scope
+
+The C++ standard allows the elision of the copy constructor (even if this results in different program behavior).  which has a side effect of enabling the compiler to treat both objects as one (see section 12.8. Copying class objects, paragraph 15; see Reference*).* The Visual C++ 8.0 compiler makes use of the flexibility that the standard provides and adds a new feature: Named Return Value Optimization (NRVO). NRVO eliminates the copy constructor and destructor of a stack-based return value. This optimizes out the redundant copy constructor and destructor calls and thus improves overall performance. It is to be noted that this could lead to different behavior between optimized and non-optimized programs (see the Optimization Side Effects section).
 
 There are some cases in which the optimization will not take place (see the Optimization Limitations section for samples). The more common ones are:
 
diff --git a/docs/toc.yml b/docs/toc.yml
@@ -3784,6 +3784,8 @@
                   href: cpp/lvalues-and-rvalues-visual-cpp.md
                 - name: Temporary objects
                   href: cpp/temporary-objects.md
+                - name: Named return value optimization
+                  href: cpp/nrvo-cpp.md
                 - name: Alignment (C++ declarations)
                   href: cpp/alignment-cpp-declarations.md
                 - name: alignof and alignas

Original file line number	Diff line number	Diff line change
`@@ -246,7 +246,7 @@ When auto is used in conjunction with a trailing return type, it just serves`
`246`	`246`
`247`	`247`	`## Function local variables`
`248`	`248`
`249`		-A variable that is declared inside a function body is called a local variable or simply a local. Non-static locals are only visible inside the function body and, if they are declared on the stack go out of scope when the function exits. When you construct a local variable and return it by value, the compiler can usually perform the return value optimization to avoid unnecessary copy operations. If you return a local variable by reference, the compiler will issue a warning because any attempt by the caller to use that reference will occur after the local has been destroyed.
	`249`	+A variable that is declared inside a function body is called a local variable or simply a local. Non-static locals are only visible inside the function body and, if they are declared on the stack go out of scope when the function exits. When you construct a local variable and return it by value, the compiler can usually perform the [named return value optimization](nrvo-cpp.md) to avoid unnecessary copy operations. If you return a local variable by reference, the compiler will issue a warning because any attempt by the caller to use that reference will occur after the local has been destroyed.
`250`	`250`
`251`	`251`	In C++ a local variable may be declared as static. The variable is only visible inside the function body, but a single copy of the variable exists for all instances of the function. Local static objects are destroyed during termination specified by `atexit`. If a static object was not constructed because the program's flow of control bypassed its declaration, no attempt is made to destroy that object.
`252`	`252`
`@@ -282,7 +282,6 @@ template<typename F, typename Tuple = tuple<T...>,`
`282`	`282`	`{`
`283`	`283`	`return apply_(std::forward<F>(f), std::forward<Tuple>(args), Indices());`
`284`	`284`	`}`
`285`		`-}`
`286`	`285`	```
`287`	`286`
`288`	`287`	`## <a name="multi_val"></a> Returning multiple values from a function`