[Tutor] Do you use doctests to show API use even when you normally use unit tests?

[Oscar Benjamin]

On Sun, 26 Apr 2020 at 05:22, boB Stepp <robertvstepp at gmail.com> wrote:
>
> They discuss the
> question of doctests versus unit tests, and, of course, heavily vote
> for unit testing as the way to go.  However, they never stop inserting
> doctests into their function and method docstrings.  I am assuming
> that they consider it best practice as to how to document how to use a
> function or method.
>
> My question is:  Is this what you would consider to be best
> documentation practice?

Best documentation practice is to think carefully about what is the
clearest way to explain something to users. Even a single very simple
example can do a lot to clarify a description. Of course the doctest
can only give examples so the description is always needed to explain
things like the full scope of the function.

You shouldn't think of doctests as an alternative to unit tests. Unit
tests are for testing the code whereas doctests are for testing the
docs. As well as helping to clarify the usage of a function to end
users doctests also remind authors of the code to keep the
documentation up to date. In a larger project this means that if any
contributor wants to change the behaviour of a function then they will
have to update the doctests which should then trigger a review of the
docstring as a whole (either by the author or by whoever reviews their
work).

--
Oscar