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:

https://github.com/iterative/dvc/blob/277d28c6cb5b0b3c2bca90dae1c869322407c57b/dvc/api.py#L38-L39

    """Returns the full URL to the data artifact specified by its `path` in a `repo`."""

https://github.com/iterative/dvc/blob/277d28c6cb5b0b3c2bca90dae1c869322407c57b/dvc/api.py#L47-L48

    """Context manager to open a file artifact as a file object."""

https://github.com/iterative/dvc/blob/277d28c6cb5b0b3c2bca90dae1c869322407c57b/dvc/api.py#L65-L67
Just end that sentence with period .

https://github.com/iterative/dvc/blob/277d28c6cb5b0b3c2bca90dae1c869322407c57b/dvc/api.py#L80-L81

    """Returns the contents of a file artifact."""

https://github.com/iterative/dvc/blob/277d28c6cb5b0b3c2bca90dae1c869322407c57b/dvc/api.py#L90-L92

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

https://github.com/iterative/dvc/blob/277d28c6cb5b0b3c2bca90dae1c869322407c57b/dvc/api.py#L98-L99

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