Python Docstring: raise vs. raises
TL;DR
raises is used to describe the possible exceptions being raised. raise is recognized by Sphinx when running autodoc and is the same as raises.
Full Explanation
PyCharm helps in using a few different styles of docstring comments.
Three which I often use are:
- NumPy Format
- Google Format
- Sphinx (much more than a format)
In all of these there is a special section for Raises which you can see in an older version of the PyCharm code tests:
The implementation for SphinxDocString we can see here there there are numerous keywords which can be recognized. Those tags then link to the list of RAISES_TAGS which can be found here.
I hope this information is useful.
You must use raises to describe exceptions raised by your method/class.
:raises: Exception: Explanation here.For example, for a ValueError exception:
:raises: ValueError: if fft_data is empty.
This works for me in latest version of PyCharm for anyone interested.
"""Some explanations.:raises WhatEverError: if there is any error"""