Add a Raises: section in docstrings where needed

[LaurentAjdnik]

As specified in https://google.github.io/styleguide/pyguide.html#doc-function-raises.

Only two functions (in simresults.py) currently have such a section, whereas so many of them can raise Errors.

[LaurentAjdnik]

BTW, shouldn't we add https://pypi.org/project/flake8-docstrings/ to CI ?

I tested it locally and the results were... kinda wild...

[HGSilveri]

As specified in https://google.github.io/styleguide/pyguide.html#doc-function-raises.

Only two functions (in simresults.py) currently have such a section, whereas so many of them can raise Errors.

@LaurentAjdnik , note the last sentence of that link you sent me:

You should not document exceptions that get raised if the API specified in the docstring is violated (because this would paradoxically make behavior under violation of the API part of the API).

Most errors we raise come exactly from violations of the API specified in the docstring, which is why they are not documented in the docstrings. Nonetheless, there can still be raised errors out there that should be documented and that we missed - if you find any of those, feel free to open a PR adding the respective Raises section.

[HGSilveri]

BTW, shouldn't we add https://pypi.org/project/flake8-docstrings/ to CI ?

I tested it locally and the results were... kinda wild...

This is a great idea, though it needs some fine-tuning. I'll open a separate issue on it.

[LaurentAjdnik]

Note the last sentence of that link you sent me:

You should not document exceptions that get raised if the API specified in the docstring is violated (because this would paradoxically make behavior under violation of the API part of the API).

Honestly, this sentence does not make much sense to me. What exactly is a "violation of the API" ? And what is not ?

Most errors we raise come exactly from violations of the API specified in the docstring, which is why they are not documented in the docstrings.

While working on #157, I counted 92 Errors raised throughout the code.

From the list I pasted in that issue, can you give me a few examples of what would be, with certainty:

• "Violations of the API"?
• "Non-violations of the API" hence requiring docstrings?

Right now, I feel like pretty much everything, except TypeErrors, could/should be included in docstrings... 😁

[HGSilveri]

Strictly speaking you're right. Every time we raise a ValueError because a value is, for example, out of range, and we did not specify this range in the docstring, then it's not a violation of the API.

However, there are times when the range is implicit (e.g. when we ask for a duration, we don't specify it should be a positive number, but it's obvious it should), and I think in cases like this, specifying the potential ValueErrors bloats the docstring unnecessarily.

So yeah, I would agree with you that generally, outside of TypeErrors, we don't follow this rule to the tee, but do so when it reasonable.

That being said, if you feel the need to attach a Raises: ValueError because of a threshold error, for example, I would rather have the threshold specified in the definition of the variable instead.

[HGSilveri]

@LaurentAjdnik is it okay if I close this issue?

[LaurentAjdnik]

BTW, shouldn't we add https://pypi.org/project/flake8-docstrings/ to CI ?
I tested it locally and the results were... kinda wild...

This is a great idea, though it needs some fine-tuning. I'll open a separate issue on it.

@HGSilveri: Shall we open this specific issue? I agree there would be some (= a lot of?...) fine-tuning before the results are satisfying.

More generally, I think there are places where we could/should add somes Raises: in the docstrings but I haven't really thought about it yet.

[HGSilveri]

@HGSilveri: Shall we open this specific issue? I agree there would be some (= a lot of?...) fine-tuning before the results are satisfying.

@LaurentAjdnik Actually, I already took care of that one (see #193 and #194).

More generally, I think there are places where we could/should add somes Raises: in the docstrings but I haven't really thought about it yet.

Alright, I'll leave it open. Do you want me to assign you then?