api: inline documentation (docstrings)

[jorgeorpinel]

I don't think we use docstrings much since the code is meant to be self-documenting for developers.

However, for dvc.api (currently a single file: https://github.com/iterative/dvc/blob/master/dvc/api.py) I think we should have significant code documentation (multi-line file and function docstrings, other comments).

Let's find a good docstring format we want to use and maintain e.g. Sphinx?

• Should probably also work on iterative/dvcx/issues/1 along with this one.

[jorgeorpinel]

Some specific suggestions:

dvc/dvc/api.py

Lines 38 to 39 in 277d28c

	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`."""

dvc/dvc/api.py

Lines 47 to 48 in 277d28c

	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."""

dvc/dvc/api.py

Lines 65 to 67 in 277d28c

	def __getattr__(self, name):
	raise AttributeError(
	"dvc.api.open() should be used in a with statement"

Just end that sentence with period .

dvc/dvc/api.py

Lines 80 to 81 in 277d28c

	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."""

dvc/dvc/api.py

Lines 90 to 92 in 277d28c

	if not repo_url or urlparse(repo_url).scheme == "":
	assert rev is None, "Custom revision is not supported for local repo"
	yield Repo(repo_url)

        assert rev is None, "Git revisions are not supported for local DVC projects."

dvc/dvc/api.py

Lines 98 to 99 in 277d28c

	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`."""

[efiop]

@jorgeorpinel Why is the second comment marked as "resolved"?

EDIT: oh, because of the PR, right...

[shcheklein]

Reopening this since I don't think we put even reasonably good enough docstrings for external API. We should describe parameters, important edge cases, etc. Alternatively we can consider linking with the docs website, but I would (as a user) prefer to have everything I would need in docstrings.

[jorgeorpinel]

True @shcheklein. I guess I thought we would do that in #3176 (so I marked this issue as closable by #2316). Do we need both issues? (This and #3176)