clarify info.clear() behavior (#3485)

* clarify info.clear() behavior

* fixes to implements docs

* Update reference/conanfile/methods/package_id.rst

Co-authored-by: Francisco Ramírez <franchuti688@gmail.com>

---------

Co-authored-by: Francisco Ramírez <franchuti688@gmail.com>

reference/conanfile/attributes/binary_model.inc

@@ -295,6 +295,11 @@ Object used exclusively in ``package_id()`` method:
             self.info.clear()
 
 
+The ``self.info.clear()`` method removes all the settings, options, requirements (``requires``, ``tool_requires``, ``python_requires``)
+and configuration (``conf``) from the ``package_id`` computation, so the ``package_id`` will always result in the same binary, irrespective
+of all those things. This would be the typical case of a header-only library, in which the packaged artifacts (files) are always identical.
+
+
 .. _reference_conanfile_attributes_package_id_modes:
 
 package_id_{embed,non_embed,unknown}_mode

reference/conanfile/methods/package_id.rst

@@ -39,23 +39,22 @@ recipe declares an option ``header_only=True`` or when ``package_type`` is
         ...
 
 Then, if no ``package_id()`` method is specified in the recipe, Conan will
-automatically manage the fPIC setting in the ``package_id`` step like this:
+automatically manage it and call ``self.info.clear()`` in the ``package_id()`` automatically,
+to make the ``package_id`` independent of settings, options, configuration and requirements.
 
-.. code-block:: python
-
-    if conanfile.options.get_safe("header_only") or conanfile.package_type is PackageType.HEADER:
-        conanfile.info.clear()
 
 If you need to implement custom behaviors in your recipes but also need this logic, it
-must be explicitly declared:
+must be explicitly declared, for example, something like this:
 
 .. code-block:: python
 
     def package_id(self):
-        if conanfile.options.get_safe("header_only") or conanfile.package_type is PackageType.HEADER:
-            conanfile.info.clear()
-        self.info.settings.rm_safe("compiler.libcxx")
-        self.info.settings.rm_safe("compiler.cppstd")
+        def package_id(self):
+            if self.package_type == "header-library":
+                self.info.clear()
+            else:
+                self.info.settings.rm_safe("compiler.libcxx")
+                self.info.settings.rm_safe("compiler.cppstd")
 
 
 .. _reference_conanfile_methods_package_id_clear:

tutorial/creating_packages/configure_options_settings.rst

@@ -258,14 +258,15 @@ there's no binary code we need to link with, but just some header files to add t
 project. In this cases the package ID of the Conan package should not be affected by
 settings or options. For that case, there's a simplified way of declaring that the
 generated package ID should not take into account settings, options or any information
-from the requirement which is using the ``self.info.clear()`` method inside another recipe
+from the requirements, which is using the ``self.info.clear()`` method inside another recipe
 method called ``package_id()``:
 
 .. code-block:: python
     
     def package_id(self):
         self.info.clear()
 
+
 We will explain the ``package_id()`` method later and explain how you can customize the
 way the package ID for the package is calculated. You can also check the :ref:`Conanfile's
 methods reference<reference_conanfile_methods>` if you want to know how this method works in

tutorial/creating_packages/other_types_of_packages/header_only_packages.rst

@@ -196,8 +196,9 @@ These are the changes introduced in the recipe:
     - We have a ``build()`` method, building the tests, but only when the standard conf ``tools.build:skip_test`` is not
       True. Use that conf as a standard way to enable/disable the testing. It is used by the helpers like ``CMake`` to
       skip the ``cmake.test()`` in case we implement the tests in CMake.
-    - We have a ``package_id()`` method calling ``self.info.clear()``. This is internally removing the settings
-      from the package ID calculation so we generate only one configuration for our header-only library.
+    - We have a ``package_id()`` method calling ``self.info.clear()``. This is internally removing all the information
+      (settings, options, requirements) from the package_id calculation so we generate only one configuration for our
+      header-only library.
 
 
 We can call ``conan create`` to build and test our package.