Fix docstrings from Conan API and some tools (#10983)

* fix docstrings

* fixes

* minor changes

* more fixes

* more fixes...

Author: czoido

conan/api/subapi/graph.py

@@ -47,16 +47,16 @@ def load_root_consumer_conanfile(self, path, profile_host, profile_build,
     @api_method
     def load_root_test_conanfile(self, path, tested_reference, profile_host, profile_build,
                                  update=None, remotes=None, lockfile=None):
-        """
-        create and initialize a root node from a test_package/conanfile.py consumer
-        @param lockfile: Might be good to lock python-requires, build-requires
-        @param path: The full path to the test_package/conanfile.py being used
-        @param tested_reference: The full RecipeReference of the tested package
-        @param profile_host:
-        @param profile_build:
-        @param update:
-        @param remotes:
-        @return: a graph Node, recipe=RECIPE_CONSUMER
+        """ Create and initialize a root node from a test_package/conanfile.py consumer
+
+        :param lockfile: Might be good to lock python-requires, build-requires
+        :param path: The full path to the test_package/conanfile.py being used
+        :param tested_reference: The full RecipeReference of the tested package
+        :param profile_host:
+        :param profile_build:
+        :param update:
+        :param remotes:
+        :return: a graph Node, recipe=RECIPE_CONSUMER
         """
 
         app = ConanApp(self.conan_api.cache_folder)
@@ -96,17 +96,17 @@ def load_graph(self, root_node, profile_host, profile_build, lockfile=None, remo
         """ Compute the dependency graph, starting from a root package, evaluation the graph with
         the provided configuration in profile_build, and profile_host. The resulting graph is a
         graph of recipes, but packages are not computed yet (package_ids) will be empty in the
-        result.
-        The result might have errors, like version or configuration conflicts, but it is still
+        result. The result might have errors, like version or configuration conflicts, but it is still
         possible to inspect it. Only trying to install such graph will fail
-        :param root_node: the starting point, an already initialized Node structure, as returned
-                          by the "load_root_node" api
+        
+        :param root_node: the starting point, an already initialized Node structure, as
+            returned by the "load_root_node" api
         :param profile_host: The host profile
         :param profile_build: The build profile
         :param lockfile: A valid lockfile (None by default, means no locked)
         :param remotes: list of remotes we want to check
-        :param update: (False by default), if Conan should look for newer versions or revisions for
-                       already existing recipes in the Conan cache
+        :param update: (False by default), if Conan should look for newer versions or
+            revisions for already existing recipes in the Conan cache
         :param check_update: For "graph info" command, check if there are recipe updates
         """
         app = ConanApp(self.conan_api.cache_folder)
@@ -129,12 +129,13 @@ def analyze_binaries(self, graph, build_mode=None, remotes=None, update=None, lo
         """ Given a dependency graph, will compute the package_ids of all recipes in the graph, and
         evaluate if they should be built from sources, downloaded from a remote server, of if the
         packages are already in the local Conan cache
+
         :param lockfile:
         :param graph: a Conan dependency graph, as returned by "load_graph()"
         :param build_mode: TODO: Discuss if this should be a BuildMode object or list of arguments
         :param remotes: list of remotes
-        :param update: (False by default), if Conan should look for newer versions or revisions for
-                       already existing recipes in the Conan cache
+        :param update: (False by default), if Conan should look for newer versions or
+            revisions for already existing recipes in the Conan cache
         """
         conan_app = ConanApp(self.conan_api.cache_folder)
         conan_app.load_remotes(remotes, update=update)

conan/api/subapi/install.py

@@ -18,9 +18,9 @@ def __init__(self, conan_api):
     @api_method
     def install_binaries(self, deps_graph, remotes=None, update=False):
         """ Install binaries for dependency graph
-        @param deps_graph: Dependency graph to intall packages for
-        @param remotes:
-        @param update:
+        :param deps_graph: Dependency graph to intall packages for
+        :param remotes:
+        :param update:
         """
         app = ConanApp(self.conan_api.cache_folder)
         app.load_remotes(remotes, update=update)
@@ -56,7 +56,7 @@ def install_consumer(self, deps_graph, generators=None, source_folder=None, outp
 
 # TODO: Look for a better location for the deployers code
 def _find_deployer(d, cache_deploy_folder):
-    """ implements the logic of finding a deployer, with priority:
+    """ Implements the logic of finding a deployer, with priority:
     - 1) absolute paths
     - 2) relative to cwd
     - 3) in the cache/extensions/deploy folder

conan/api/subapi/new.py

@@ -47,7 +47,7 @@ def get_template(self, template_folder):
 
     @api_method
     def get_home_template(self, template_name):
-        """ load a template from the Conan home templates/command/new folder
+        """ Load a template from the Conan home templates/command/new folder
         """
         folder_template = os.path.join(self.conan_api.home_folder, "templates", "command/new",
                                        template_name)

conan/api/subapi/profiles.py

@@ -12,24 +12,24 @@ def __init__(self, conan_api):
 
     def get_default_host(self):
         """
-        @return: the path to the default "host" profile, either in the cache or as defined by
-        the user in configuration
+        :return: the path to the default "host" profile, either in the cache or as defined
+            by the user in configuration
         """
         loader = ProfileLoader(self._cache)
         return loader.get_default_host()
 
     def get_default_build(self):
         """
-        @return: the path to the default "build" profile, either in the cache or as defined by
-        the user in configuration
+        :return: the path to the default "build" profile, either in the cache or as
+            defined by the user in configuration
         """
         loader = ProfileLoader(self._cache)
         return loader.get_default_build()
 
     def get_profile(self, profiles, settings=None, options=None, conf=None, cwd=None):
-        """ Computes a Profile as the result of aggregating all the user arguments, first
-        it loads the "profiles", composing them in order (last profile has priority), and finally
-        adding the individual settings, options (priority over the profiles)
+        """ Computes a Profile as the result of aggregating all the user arguments, first it
+        loads the "profiles", composing them in order (last profile has priority), and
+        finally adding the individual settings, options (priority over the profiles)
         """
         assert profiles and isinstance(profiles, list), "Please provide at least 1 profile"
         loader = ProfileLoader(self._cache)
@@ -41,17 +41,17 @@ def get_profile(self, profiles, settings=None, options=None, conf=None, cwd=None
 
     def get_path(self, profile, cwd=None, exists=True):
         """
-        @return: the resolved path of the given profile name, that could be in the cache, or
-        local, depending on the "cwd"
+        :return: the resolved path of the given profile name, that could be in the cache,
+            or local, depending on the "cwd"
         """
         loader = ProfileLoader(self._cache)
         profile_path = loader.get_profile_path(profile, cwd, exists=exists)
         return profile_path
 
     def list(self):
         """
-        list all the profiles file sin the cache
-        @return: an alphabetically ordered list of profile files in the default cache location
+        List all the profiles file sin the cache
+        :return: an alphabetically ordered list of profile files in the default cache location
         """
         profiles = []
         profiles_path = self._cache.profiles_path
@@ -67,7 +67,7 @@ def list(self):
 
     def detect(self):
         """
-        @return: an automatically detected Profile, with a "best guess" of the system settings
+        :return: an automatically detected Profile, with a "best guess" of the system settings
         """
         profile = Profile()
         from conans.client.conf.detect import detect_defaults_settings

conan/api/subapi/search.py

@@ -81,9 +81,8 @@ def recipe_revisions(self, expression, remote=None, none_revision_allowed=True):
 
     @api_method
     def package_revisions(self, expression, query=None, remote=None):
-        """
-        Resolve an expression like lib*/1*#*:9283*, filtering by query and obtaining all the package
-        revisions
+        """ Resolve an expression like lib*/1*#*:9283*, filtering by query and obtaining all the package revisions
+
         :param expression: lib*/1*#*:9283*
         :param query: package configuration query like "os=Windows AND (arch=x86 OR compiler=gcc)"
         :param remote: Remote object

conan/tools/env/environment.py

@@ -192,10 +192,13 @@ def remove(self, name, value):
         self._values[name].remove(value)
 
     def compose_env(self, other):
-        """
-        self has precedence, the "other" will add/append if possible and not conflicting, but
-        self mandates what to do. If self has define(), without placeholder, that will remain
-        :type other: Environment
+        """ 
+        ``self`` has precedence, the "other" will add/append if possible and not
+        conflicting, but ``self`` mandates what to do. If ``self`` has ``define()``, without
+        placeholder, that will remain
+
+        :param other: the "other" environment
+        :type other: class:`Environment`
         """
         for k, v in other._values.items():
             existing = self._values.get(k)
@@ -208,7 +211,8 @@ def compose_env(self, other):
 
     def __eq__(self, other):
         """
-        :type other: Environment
+        :param other: the "other" environment
+        :type other: class:`Environment`
         """
         return other._values == self._values
 
@@ -240,7 +244,7 @@ def get(self, name, default=None):
         return v.get_value(self._subsystem, self._pathsep)
 
     def items(self):
-        """returns {str: str} (varname: value)"""
+        """returns ``{str: str}`` (varname: value)"""
         return {k: v.get_value(self._subsystem, self._pathsep)
                 for k, v in self._values.items()}.items()
 

conan/tools/files/copy_pattern.py

@@ -8,28 +8,26 @@
 
 def copy(conanfile, pattern, src, dst, keep_path=True, excludes=None,
          ignore_case=True, copy_symlink_folders=True):
-    """
-        It will copy the files matching the pattern from the src folder to the dst, including the
+    """ It will copy the files matching the pattern from the src folder to the dst, including the
         symlinks to files. If a folder from "src" doesn't contain any file to be copied, it won't be
         created empty at the "dst".
         If in "src" there are symlinks to folders, they will be created at "dst" irrespective if
         they (or the folder where points) have files to be copied or not, unless
         "copy_symlink_folders=False" is specified.
 
-        param pattern: an fnmatch file pattern of the files that should be copied. Eg. *.dll
-        param dst: the destination local folder, wrt to current conanfile dir, to which
-                   the files will be copied. Eg: "bin"
-        param src: the source folder in which those files will be searched. This folder
-                   will be stripped from the dst name. Eg.: lib/Debug/x86
-        param keep_path: False if you want the relative paths to be maintained from
-                         src to dst folders, or just drop. False is useful if you want
-                         to collect e.g. many *.libs among many dirs into a single
-                         lib dir
-        param excludes: Single pattern or a tuple of patterns to be excluded from the copy
-        param ignore_case: will do a case-insensitive pattern matching when True
-        param copy_symlink_folders: Copy the symlink folders at the "dst" folder.
-
-        return: list of copied files
+        :param pattern: an fnmatch file pattern of the files that should be copied. Eg. .dll
+        :param dst: the destination local folder, wrt to current conanfile dir, to which
+            the files will be copied. Eg: "bin"
+        :param src: the source folder in which those files will be searched. This folder
+            will be stripped from the dst name. Eg.: lib/Debug/x86
+        :param keep_path: False if you want the relative paths to be maintained from src
+            to dst folders, or just drop. False is useful if you want to collect e.g. many
+            .libs among many dirs into a single lib dir
+        :param excludes: Single pattern or a tuple of patterns to be excluded from the
+            copy
+        :param ignore_case: will do a case-insensitive pattern matching when True
+        :param copy_symlink_folders: Copy the symlink folders at the "dst" folder.
+        :return: list of copied files
         """
     assert src != dst
     assert not pattern.startswith("..")

conan/tools/files/files.py

@@ -168,7 +168,8 @@ def _download_file(file_url):
 
 def rename(conanfile, src, dst):
     """
-    rename a file or folder to avoid "Access is denied" error on Windows
+    Rename a file or folder to avoid "Access is denied" error on Windows
+
     :param conanfile: conanfile object
     :param src: Source file or folder
     :param dst: Destination file or folder
@@ -254,14 +255,14 @@ def unzip(conanfile, filename, destination=".", keep_permissions=False, pattern=
           strip_root=False):
     """
     Unzip a zipped file
+
     :param filename: Path to the zip file
     :param destination: Destination folder (or file for .gz files)
-    :param keep_permissions: Keep the zip permissions. WARNING: Can be
-    dangerous if the zip was not created in a NIX system, the bits could
-    produce undefined permission schema. Use this option only if you are sure
-    that the zip was created correctly.
-    :param pattern: Extract only paths matching the pattern. This should be a
-    Unix shell-style wildcard, see fnmatch documentation for more details.
+    :param keep_permissions: Keep the zip permissions. WARNING: Can be dangerous if the
+        zip was not created in a NIX system, the bits could produce undefined permission
+        schema. Use this option only if you are sure that the zip was created correctly.
+    :param pattern: Extract only paths matching the pattern. This should be a Unix
+        shell-style wildcard, see fnmatch documentation for more details.
     :param flat: If all the contents are in a single dir, flat that directory.
     :return:
     """

conan/tools/files/patches.py

@@ -26,8 +26,9 @@ def emit(self, record):
 
 
 def patch(conanfile, base_path=None, patch_file=None, patch_string=None, strip=0, fuzz=False, **kwargs):
-    """ Applies a diff from file (patch_file)  or string (patch_string)
-        in base_path directory or current dir if None
+    """ Applies a diff from file (patch_file)  or string (patch_string) in base_path directory
+    or current dir if None
+
     :param base_path: Base path where the patch should be applied.
     :param patch_file: Patch file that should be applied.
     :param patch_string: Patch string that should be applied.
@@ -68,34 +69,32 @@ def patch(conanfile, base_path=None, patch_file=None, patch_string=None, strip=0
 
 def apply_conandata_patches(conanfile):
     """
-    Applies patches stored in 'conanfile.conan_data' (read from 'conandata.yml' file). It will apply
-    all the patches under 'patches' entry that matches the given 'conanfile.version'. If versions are
-    not defined in 'conandata.yml' it will apply all the patches directly under 'patches' keyword.
-
-    Example of 'conandata.yml' without versions defined:
-
-    ```
-    patches:
-    - patch_file: "patches/0001-buildflatbuffers-cmake.patch"
-      base_path: "source_subfolder"
-    - patch_file: "patches/0002-implicit-copy-constructor.patch"
-      patch_type: backport
-      patch_source: https://github.com/google/flatbuffers/pull/5650
-      patch_description: Needed to build with modern clang compilers (adapted to 1.11.0 tagged sources).
-    ```
-
-    Example of 'conandata.yml' with different patches for different versions:
-    ```
-    patches:
-      "1.11.0":
+    Applies patches stored in 'conanfile.conan_data' (read from 'conandata.yml' file). It
+    will apply all the patches under 'patches' entry that matches the given
+    'conanfile.version'. If versions are not defined in 'conandata.yml' it will apply all
+    the patches directly under 'patches' keyword.
+
+    Example of 'conandata.yml' without versions defined::
+
+        patches:
         - patch_file: "patches/0001-buildflatbuffers-cmake.patch"
+        base_path: "source_subfolder"
         - patch_file: "patches/0002-implicit-copy-constructor.patch"
-          patch_type: backport
-          patch_source: https://github.com/google/flatbuffers/pull/5650
-          patch_description: Needed to build with modern clang compilers (adapted to 1.11.0 tagged sources).
-      "1.12.0":
-        - patch_file: "patches/0001-buildflatbuffers-cmake.patch"
-    ```
+        patch_type: backport
+        patch_source: https://github.com/google/flatbuffers/pull/5650
+        patch_description: Needed to build with modern clang compilers (adapted to 1.11.0 tagged sources).
+
+    Example of 'conandata.yml' with different patches for different versions::
+
+        patches:
+        "1.11.0":
+            - patch_file: "patches/0001-buildflatbuffers-cmake.patch"
+            - patch_file: "patches/0002-implicit-copy-constructor.patch"
+            patch_type: backport
+            patch_source: https://github.com/google/flatbuffers/pull/5650
+            patch_description: Needed to build with modern clang compilers (adapted to 1.11.0 tagged sources).
+        "1.12.0":
+            - patch_file: "patches/0001-buildflatbuffers-cmake.patch"
     """
 
     patches = conanfile.conan_data.get('patches')

conans/server/store/disk_adapter.py

@@ -13,7 +13,7 @@ class ServerDiskAdapter(object):
     for conan operations"""
     def __init__(self, base_url, base_storage_path):
         """
-        :param: base_url Base url for generate urls to download and upload operations"""
+        :param base_url Base url for generate urls to download and upload operations"""
 
         self.base_url = base_url
         # URLs are generated removing this base path