Add Include What You Use pragmas to help IWYU find the correct headers to include.

[daantimmer]

Include What You Use (IWYU) (A tool for use with clang to analyze #includes in C and C++ source files) is able to fix (read: add and remove) includes automatically based on what types are being referenced in a source and or header file.

However, it fails to properly include yaml-cpp's headers because the forward declarations and actual implementation are separated across multiple includes. Which IWYU will not able to fix automatically. Resulting in linking errors because it didn't include the implementation of a function/class template.

An example of IWYU's usage can be seen in googletest/googlemock:
https://github.com/google/googletest/blob/1b96fa13f549387b7549cc89e1a785cf143a1a50/googletest/include/gtest/gtest-matchers.h#L35-L37
This marks the gtest-matchers.h as a private include, and instead of including gtest-matchers.h gtest/gtest.h should be included instead.
The pragma: friend directives mark this file for 'private use' from all the headers inside the gtest/ and gmock/ folders

https://github.com/google/googletest/blob/1b96fa13f549387b7549cc89e1a785cf143a1a50/googletest/include/gtest/gtest.h#L63-L72
Shows how that gtest/gtest.h is 'exporting' symbols found in all the 'private' headers.

Using these directives gives IWYU the tools to include gtest/gtest.h whenever you depend on any type defined in any of its 'private headers'.

Using IWYU on yaml-cpp results in the inclusion of, for example, yaml-cpp/node/node.h, alone. Which is correct-ish when you use YAML::Node and it will compile but will fail to link because it is missing the inclusion of yaml-cpp/impl.h

I would like to propose to add IWYU directives to private/public headers so it becomes IWYU compatible.