set_version and set_name flexibility

reference/conanfile/methods/set_name.rst

@@ -40,6 +40,29 @@ command line argument we should do:
             self.name = self.name or load(self, "name.txt")
 
 
+The ``set_name()`` method can decide to define the ``name`` value, irrespective of the potential
+``--name=xxx`` command line argument, that can be even completely ignored by ``set_name()``. It 
+is the responsibility of the developer to provide a correct ``set_name()``:
+
+.. code-block:: python
+
+    def set_name(self):
+        # This will always assign "pkg" as name, ignoring ``--name`` command line argument
+        # and without erroring or warning
+        self.name = "pkg"
+
+
+If a command line argument ``--name=xxx`` is provided, it will be initialized in the ``self.name``
+attribute, so ``set_name()`` method can read and use it:
+
+.. code-block:: python
+
+    def set_name(self):
+        # Takes the provided command line ``--name`` argument and creates a name appending to
+        # it the ".extra" string
+        self.name = self.name + ".extra"
+
+
 .. warning::
 
     The ``set_name()`` method is an alternative to the ``name`` attribute. It is

reference/conanfile/methods/set_version.rst

@@ -54,7 +54,30 @@ could be done with:
             self.version = git.run("describe --tags")
 
 
+The ``set_version()`` method can decide to define the ``version`` value, irrespective of the potential
+``--version=xxx`` command line argument, that can be even completely ignored by ``set_version()``. It 
+is the responsibility of the developer to provide a correct ``set_version()``:
+
+.. code-block:: python
+
+    def set_version(self):
+        # This will always assign "2.1" as version, ignoring ``--version`` command line argument
+        # and without erroring or warning
+        self.version = "2.1"
+
+
+If a command line argument ``--version=xxx`` is provided, it will be initialized in the ``self.version``
+attribute, so ``set_version()`` method can read and use it:
+
+.. code-block:: python
+
+    def set_version(self):
+        # Takes the provided command line ``--version`` argument and creates a version appending to
+        # it the ".extra" string
+        self.version = self.version + ".extra"
+
+
 .. warning::
 
     The ``set_version()`` method is an alternative to the ``version`` attribute. It is
-    not advised or supported to define both a ``version`` attribute and a ``set_version()`` method. 
+    not advised or supported to define both a ``version`` class attribute and a ``set_version()`` method.