The doc-string state pre- and post-conditions of a function and what it does in abstract terms. It should not say anything implementation specific. For example

The doc-string state pre- and post-conditions of a function and what it does in abstract terms. It should not say anything implementation specific. For example, the doc string of "search" tells you the returned list is sorted afterwards. It should maybe tell you the complexity of its algorithm like O(n log(n)). It should NOT state which algorithm (QuickSort, TimSort, etc) it uses. Comments in the source code can explain the choice of algorithm.