[question] Clarifications needed in documentation for 2.0

[ZbigniewRA]

In Conan 2.0 documentation page self.cpp and self.cpp_info the following sections are not clear to someone not familiar with Conan (like me):

1.  .builddirs Ordered list with build scripts directory paths.
               CMakeDeps generator will search in these dirs for files like findXXX.cmake or include(“XXX.cmake”)
   

   builddirs usually are "dirs where the code is built". So the name itself is misleading.
   Here it sounds like "dirs where the package delivers scripts to be used by the consumer's buildsystem". I think that more clarification here would avoid confusion, so:

   • not a builddir in the usual sense,
   • not build scripts used to build the package,
   • not really build scripts used to consume the package (as CMakeDeps will generate those),
   • but helper build scripts provided by package for use by the consumer.

2.  .system_libs Ordered list with the system library names.
   

   It is not clear what system libs are. It is also not obvious that consumers must link against those.
   Adding more clarification would help, like: "Libraries that consumers must link to, that are assumed to exist in the environment (i.e. provided by the compiler, operating system, or manually by the consumer of the package)."

3.  .components Dictionary with different components a package may have.
   

   It is not clear what it would mean to fill the top-level self.cpp_info and also adding components inside it.
   Would self.cpp_info.libs be libraries required for all components? Or libraries provided by all components? Or is it not allowed?
   Also clarifying here that this is a dictionary of CppInfo objects would be helpful.

4. It is also not clear what my_pkg::my_pkg means for a package that has sub-components:

   • Does it mean we use only what is declared in top-level self.cpp_info?
   • Does it mean we use all sub-components?

• [X] I've read the CONTRIBUTING guide.