Clarify C++/WinRT namespace header file rules (#4182)

It is not true that including a namespace header automatically
includes all parent namespace headers.

Do not confuse the issue with declarations and implementations.
Just say that you need to include the header for any class
you use.

Author: oldnewthing

uwp/cpp-and-winrt-apis/consume-apis.md

@@ -52,31 +52,21 @@ In fact, that projected value is a proxy; it's essentially just a smart pointer
 When the `contosoUri` value falls out of scope, it destructs, and releases its reference to the default interface. If that reference is the last reference to the backing Windows Runtime **Windows.Foundation.Uri** object, the backing object destructs as well.
 
 > [!TIP]
-> A *projected type* is a wrapper over a runtime class for purposes of consuming its APIs. A *projected interface* is a wrapper over a Windows Runtime interface.
+> A *projected type* is a wrapper over a Windows Runtime type for purposes of consuming its APIs. For example, a *projected interface* is a wrapper over a Windows Runtime interface.
 
 ## C++/WinRT projection headers
-To consume Windows namespace APIs from C++/WinRT, you include headers from the `%WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt` folder. It's common for a type in a subordinate namespace to reference types in its immediate parent namespace. Consequently, each C++/WinRT projection header automatically includes its parent namespace header file; so you don't *need* to explicitly include it. Although, if you do, there will be no error.
+To consume Windows namespace APIs from C++/WinRT, you include headers from the `%WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt` folder. You must include the headers corresponding to each namespace you use.
 
-For example, for the [**Windows::Security::Cryptography::Certificates**](/uwp/api/windows.security.cryptography.certificates) namespace, the equivalent C++/WinRT type definitions reside in `winrt/Windows.Security.Cryptography.Certificates.h`. Types in **Windows::Security::Cryptography::Certificates** require types in the parent **Windows::Security::Cryptography** namespace; and types in that namespace could require types in its own parent, **Windows::Security**.
+For example, for the [**Windows::Security::Cryptography::Certificates**](/uwp/api/windows.security.cryptography.certificates) namespace, the equivalent C++/WinRT type definitions reside in `winrt/Windows.Security.Cryptography.Certificates.h`. Including that header gives you access to all the types in the [**Windows::Security::Cryptography::Certificates**](/uwp/api/windows.security.cryptography.certificates) namespace.
 
-So, when you include `winrt/Windows.Security.Cryptography.Certificates.h`, that file in turn includes `winrt/Windows.Security.Cryptography.h`; and `winrt/Windows.Security.Cryptography.h` includes `winrt/Windows.Security.h`. That's where the trail stops, since there is no `winrt/Windows.h`. This transitive inclusion process stops at the second-level namespace.
+Sometimes, one namespace header will include portions of related namespace headers, but you shouldn't rely on this implementation detail. Explicitly include the headers for the namespaces you use.
 
-This process transitively includes the header files that provide the necessary *declarations* and *implementations* for the classes defined in parent namespaces.
+For example, the [**Certificate::GetCertificateBlob**](/uwp/api/windows.security.cryptography.certificates.certificate.getcertificateblob) method returns an
+[**Windows::Storage::Streams::IBuffer**](/uwp/api/windows.storage.streams.ibuffer) interface.
+Before calling the [**Certificate::GetCertificateBlob**](/uwp/api/windows.security.cryptography.certificates.certificate.getcertificateblob) method,
+you must include the `winrt/Windows.Storage.Streams.h` namespace header file to ensure that you can receive and operate on the returned [**Windows::Storage::Streams::IBuffer**](/uwp/api/windows.storage.streams.ibuffer).
 
-A member of a type in one namespace can reference one or more types in other, unrelated, namespaces. In order for the compiler to compile these member definitions successfully, the compiler needs to see the type declarations for the closure of all these types. Consequently, each C++/WinRT projection header includes the namespace headers it needs to *declare* any dependent types. Unlike for parent namespaces, this process does *not* pull in the *implementations* for referenced types.
-
-> [!IMPORTANT]
-> When you want to actually *use* a type (instantiate, call methods, etc.) declared in an unrelated namespace, you must include the appropriate namespace header file for that type. Only *declarations*, not *implementations*, are automatically included.
-
-For example, if you only include `winrt/Windows.Security.Cryptography.Certificates.h`, then that causes declarations to be pulled in from these namespaces (and so on, transitively).
-
-- Windows.Foundation
-- Windows.Foundation.Collections
-- Windows.Networking
-- Windows.Storage.Streams
-- Windows.Security.Cryptography
-
-In other words, some APIs are forward-declared in a header that you've included. But their definitions are in a header that you haven't yet included. So, if you then call [**Windows::Foundation::Uri::RawUri**](/uwp/api/windows.foundation.uri.rawuri), then you'll receive a linker error indicating that the member is undefined. The solution is to explicitly `#include <winrt/Windows.Foundation.h>`. In general, when you see a linker error such as this, include the header named for the API's namespace, and rebuild.
+Forgetting to include the required namespace headers before using types in that namespace is a common source of build errors.
 
 ## Accessing members via the object, via an interface, or via the ABI
 With the C++/WinRT projection, the runtime representation of a Windows Runtime class is no more than the underlying ABI interfaces. But, for your convenience, you can code against classes in the way that their author intended. For example, you can call the **ToString** method of a [**Uri**](/uwp/api/windows.foundation.uri) as if that were a method of the class (in fact, under the covers, it's a method on the separate **IStringable** interface).

uwp/cpp-and-winrt-apis/faq.yml

@@ -74,7 +74,7 @@ sections:
       - question: |
           Why is the compiler giving me a "C3779: consume_Something: function that returns 'auto' cannot be used before it is defined" error?
         answer: |
-          You're consuming an API from the Windows namespace headers for the C++/WinRT projection (in the **winrt** namespace), and the API is forward-declared in a header that you've included, but its definition is in a header that you haven't yet included. Include the header named for the API's namespace, and rebuild. For more info, see [C++/WinRT projection headers](consume-apis.md#cwinrt-projection-headers).
+          You're using a Windows Runtime object without having first included the corresponding namespace header file. Include the header named for the API's namespace, and rebuild. For more info, see [C++/WinRT projection headers](consume-apis.md#cwinrt-projection-headers).
 
       - question: |
           Why is the linker giving me a "LNK2019: Unresolved external symbol" error?
@@ -87,7 +87,7 @@ sections:
 
           It's important that you resolve any linker errors that you can by linking **WindowsApp.lib** instead of an alternative static-link library, otherwise your application won't pass the [Windows App Certification Kit](../debug-test-perf/windows-app-certification-kit.md) tests used by Visual Studio and by the Microsoft Store to validate submissions (meaning that it consequently won't be possible for your application to be successfully ingested into the Microsoft Store).
 
-          **Relatively rare**: if the unresolved symbol is an API from the Windows namespace headers for the C++/WinRT projection (in the **winrt** namespace), then the API is forward-declared in a header that you've included, but its definition is in a header that you haven't yet included. Include the header named for the API's namespace, and rebuild. For more info, see [C++/WinRT projection headers](consume-apis.md#cwinrt-projection-headers).
+          If the unresolved symbol is a constructor, you may have forgotten to include the namespace header file for the class being constructed. Include the header named for the class's namespace, and rebuild. For more info, see [C++/WinRT projection headers](consume-apis.md#cwinrt-projection-headers).
 
       - question: |
           Why am I getting a "class not registered" exception?

uwp/cpp-and-winrt-apis/get-started.md

@@ -75,7 +75,7 @@ The headers contain Windows APIs projected into C++/WinRT. In other words, for e
 > [!IMPORTANT]
 > Whenever you want to use a type from a Windows namespaces, you must `#include` the corresponding C++/WinRT Windows namespace header file, as shown above. The *corresponding* header is the one with the same name as the type's namespace. For example, to use the C++/WinRT projection for the [**Windows::Foundation::Collections::PropertySet**](/uwp/api/windows.foundation.collections.propertyset) runtime class, include the `winrt/Windows.Foundation.Collections.h` header.
 > 
-> It's usual for a C++/WinRT projection header to automatically include its parent namespace header file. So, for example, `winrt/Windows.Foundation.Collections.h` includes `winrt/Windows.Foundation.h`. But you shouldn't rely on this behavior, since it's an implementation detail that changes over time. You must explicitly include any headers that you need.
+> It is common for a C++/WinRT projection header to automatically include related namespace header files. For example, `winrt/Windows.Foundation.Collections.h` includes `winrt/Windows.Foundation.h`. But you shouldn't rely on this behavior, since it's an implementation detail that changes over time. You must explicitly include any headers that you need.
 
 ```cppwinrt
 using namespace winrt;