From f65237761f2685ef54303e03843ca3ee603a2493 Mon Sep 17 00:00:00 2001
From: Jorge Orpinel <jorge@orpinel.com>
Date: Mon, 13 Jan 2020 14:27:04 -0600
Subject: [PATCH 1/2] api: improve existing docstrings per
 https://github.com/iterative/dvc/issues/3092#issuecomment-572394156

---
 dvc/api.py | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/dvc/api.py b/dvc/api.py
index 655594bf1c..00bd312a53 100644
--- a/dvc/api.py
+++ b/dvc/api.py
@@ -45,7 +45,10 @@ class SummonError(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`.
+    """
     with _make_repo(repo, rev=rev) as _repo:
         abspath = os.path.join(_repo.root_dir, path)
         out, = _repo.find_outs_by_path(abspath)
@@ -54,7 +57,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,
@@ -73,7 +76,7 @@ def __init__(self, func, args, kwds):
 
     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."
         )
 
 
@@ -87,7 +90,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:
@@ -97,7 +100,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 urlparse(repo_url).scheme == "":
-        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:
@@ -105,7 +110,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:

From 2b818e203f8deb5ca7b2684b836df0ff3f748088 Mon Sep 17 00:00:00 2001
From: Jorge Orpinel <jorge@orpinel.com>
Date: Fri, 17 Jan 2020 17:40:02 -0600
Subject: [PATCH 2/2] api: note get_url doesn't chekc file existence per
 https://github.com/iterative/dvc/pull/3130#discussion_r367359439

---
 dvc/api.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/dvc/api.py b/dvc/api.py
index bac8c99da8..5c3401bbe5 100644
--- a/dvc/api.py
+++ b/dvc/api.py
@@ -58,6 +58,7 @@ def get_url(path, repo=None, rev=None, remote=None):
     """
     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: