If you want to see doctrings in action, take a look at Salt (https://saltproject.io/). They’re used to build all the module documentation (https://docs.saltproject.io/en/latest/py-modindex.html) using sphinx and they won’t accept new modules without them.

i use interrogate

Which has a fun bug. Uses ast to compile every module. If a module contains a compile error, get a traceback showing only the one line that contains the issue, but not the module path nor the line #

The only way to find the issue is to just test your code base and ignore interrogate until code base is more mature.

interrogate author and maintainers: UX … what’s that?

The most obvious bug in the history of bugs … setuptools maintainers, oh that's a feature request

Yes, because it shows up in editors when hovering. We’re not forced, but as a lead, I encourage it.

Docstrings are important and their role is different than comments. They give an overview how the function works, explain parameters and sometimes give examples how to use them. You can generate documentation using sphinx from Docstrings, and as others said IDEs use docstrings to show you information about function you’re using.

Comments are just text that gets ignored by interpreter. You can add explanation to code if it’s not self explanatory, but they’re not useful outside of the immediate area being commented on.

Other languages also have documentation options that is separate from comments, e.g. JavaDoc. The syntax is usually similar to coment, but slightly different to differentiate it from comments (extra * in multiline comment).