Merge pull request #3130 from jorgeorpinel/master

api: better code documentation

dvc/api.py

@@ -55,7 +55,11 @@ class UrlNotDvcRepoError(DvcException):
 
 
 def get_url(path, repo=None, rev=None, remote=None):
-    """Returns an url of a resource specified by path in repo"""
+    """
+    Returns the full URL to the data artifact specified by its `path` in a
+    `repo`.
+    NOTE: There is no guarantee that the file actually exists in that location.
+    """
     try:
         with _make_repo(repo, rev=rev) as _repo:
             abspath = os.path.join(_repo.root_dir, path)
@@ -67,7 +71,7 @@ def get_url(path, repo=None, rev=None, remote=None):
 
 
 def open(path, repo=None, rev=None, remote=None, mode="r", encoding=None):
-    """Opens a specified resource as a file descriptor"""
+    """Context manager to open a file artifact as a file object."""
     args = (path,)
     kwargs = {
         "repo": repo,
@@ -86,7 +90,7 @@ class _OpenContextManager(GCM):
 
     def __getattr__(self, name):
         raise AttributeError(
-            "dvc.api.open() should be used in a with statement"
+            "dvc.api.open() should be used in a with statement."
         )
 
 
@@ -100,7 +104,7 @@ def _open(path, repo=None, rev=None, remote=None, mode="r", encoding=None):
 
 
 def read(path, repo=None, rev=None, remote=None, mode="r", encoding=None):
-    """Read a specified resource into string"""
+    """Returns the contents of a file artifact."""
     with open(
         path, repo=repo, rev=rev, remote=remote, mode=mode, encoding=encoding
     ) as fd:
@@ -110,7 +114,9 @@ def read(path, repo=None, rev=None, remote=None, mode="r", encoding=None):
 @contextmanager
 def _make_repo(repo_url, rev=None):
     if not repo_url or os.path.exists(repo_url):
-        assert rev is None, "Custom revision is not supported for local repo"
+        assert (
+            rev is None
+        ), "Git revisions are not supported for local DVC projects."
         yield Repo(repo_url)
     else:
         with external_repo(url=repo_url, rev=rev) as repo:
@@ -118,7 +124,7 @@ def _make_repo(repo_url, rev=None):
 
 
 def summon(name, repo=None, rev=None, summon_file="dvcsummon.yaml", args=None):
-    """Instantiate an object described in the summon file."""
+    """Instantiate an object described in the `summon_file`."""
     with prepare_summon(
         name, repo=repo, rev=rev, summon_file=summon_file
     ) as desc: