[question] Clarifications needed in documentation for 2.0
- Dominant language
- C++
- Stars
- 125
- Forks
- 382
- Avg merge
- 22h 39m
- Merged PRs (30d)
- 21
Description
In Conan 2.0 documentation page [self.cpp and self.cpp_info](https://docs.conan.io/en/2.0-alpha/reference/conanfile/other/cpp_info.html) 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](https://github.com/conan-io/conan/blob/develop/.github/CONTRIBUTING.md).
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.