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.

[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