Dvc: 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)

[shcheklein]

@jorgeorpinel it feels they have a bit different purpose - one is about the style guide, this one is about actual docs (e.g. do we need to specify arguments, return values, may be even examples? etc?)

[jorgeorpinel]

OK

do we need to specify arguments, return values, may be even examples? etc?

I think definitely yes arguments and return values. Not sure about examples... Maybe not for now but link to the new api ref in dvc.org (Do we need a new redirect similar to man.dvc.org BTW? api.dvc.org/{fn})

BUT we still need to decide on #3176 before I can write these parts of the docstrings.

p.s. does this issue have a priority? None assigned at the moment. And #3176 has "p3 nice to have". Cc @efiop