target_link_libraries documentation should mention effect of properties of the linked target
When linking to another target with target_link_libraries, properties like INTERFACE_INCLUDE_DIRECTORIES affect the linking target. This should be mentioned explicitly in target_link_libraries documentation, ideally with some examples. Currently this feature is hidden in INTERFACE_INCLUDE_DIRECTORIES property documentation. "When target dependencies are specified using target_link_libraries(), CMake will read this property from all target dependencies to determine the build properties of the consumer." Said in other words, reading target_link_libraries and target_include_directories documentation one still does not get a clear understanding of what is the best way to specify include directories for both the depended and the depending target.
It's probably also unclear if then the includes of the linked library will become part of the INTERFACE_INCLUDE_DIRECTORIES of the linking library. Let's say that the system acts as if a target_include_directories was called for the linking target: Will the effect be as if it was invoked with PUBLIC or PRIVATE? This is relevant if a third library/executable is linked to the linking library.