Can someone tell me the differences between the following docstring parameters?
:type and :param
I've seen both being used to specify the type of method arguments, but I don't think they do exactly the same. Is one of them for the programmer and the other for the IDE or something like that?
:rtype, :return and :returns
Especially :return and :returns seem very similar, so which are to use in which situation?
These conventions are used by the Sphinx documentation tool, which was originally designed for processing Python docs. Its popularity has, however, led it to be extended into other domains, defined in the Sphinx documentation as "a collection of markup (reStructuredText directives and roles) to describe and link to objects belonging together".
According to the linked page :return comes from the Python domain, :returns from the JavaScript domain, and they both appear to be used for the same thing (i.e. documenting the return value of a function or method). In practice :returns appears so infrequently one wonders whether it's a documentation typo.
:rtype specifies the return type, and will create a link to the type definition if that's possible (i.e. if Sphinx can find the definition in the code you are documenting).