Improve internal header documentation (#7483)

HeadersImports.md

@@ -34,6 +34,12 @@ In Swift Package Manager, it's a library target.
   should be located among the source files. [Xcode](https://stackoverflow.com/a/8016333) refers to
   these as "Project Headers".
 
+* *Library C++ Internal Headers* - In CocoaPods, C++ internal headers should not be included
+  in the `source_files` attribute. Instead, they should be defined with the `preserve_paths`
+  attribute to avoid filename collisions in the generated Xcode workspace. C++ does not assume
+  a global header map, so if filenames are qualified at all, it's generally by directory, not a
+  filename prefix like in Objective-C.
+
 ## Imports - For Header File Consumers
 
 * *Headers within the Library* - Use a repo-relative path for all of the header types above.
@@ -42,9 +48,12 @@ In Swift Package Manager, it's a library target.
 
 * *Private Headers from other Libraries* - Import a private umbrella header like
   `FirebaseCore/Sources/Private/FirebaseCoreInternal.h`. For CocoaPods, these files should be
-  added to the podspec in the `preserved_path` attribute like:
+  added to the podspec in the `source_files` attribute like:
 ```
-  s.preserve_paths = 'Interop/Auth/Public/*.h', 'FirebaseCore/Sources/Private/*.h'
+  s.source_files = [ 'FirebaseFoo/Sources/**/*.[mh]'
+                     'Interop/Auth/Public/*.h',
+                     'FirebaseCore/Sources/Private/*.h',
+                   ]
 ```
 
 * *Headers from an external dependency* - Do a module import for Swift Package Manager and an

Interop/FirebaseComponentSystem.md

@@ -348,7 +348,7 @@ Adding dependencies is easy once components are registered with Core. Let's take
 Functions above and add a dependency to `FIRAuthInterop` defined above.
 
 **Important**: You will also need to add `FirebaseAuthInterop` headers to your
-               product's podspec `preserved_paths` attribute for CocoaPods and something
+               product's podspec `source_files` attribute for CocoaPods and something
                comparable for any other package manager supported. Note, for Swift Package Manager,
                nothing special is needed as long as all the pods and headers are in the same repo.