[MRG+1] DOC: Add Raises Section

[maniteja123]

Added Raises section to utils.validation. This was an idea by @rvraghav93 in #6198 which seemed helpful. If feasible can do it for other modules too. Otherwise, please close the PR.

[GaelVaroquaux]

Looks good in general. This does beg the question of how to maintain this information. However, the question applies to any type of docstring, so it shouldn't deter us from merging this.

You have my +1

[maniteja123]

In the first attempt, it felt that at automated way of finding the raised exceptions by the method would require knowing all the functions used by this method. Somewhat similar to the way parameters of a function are extracted.

That said it would be really difficult IMO to take care of recursive calls and parameters passed through those calls to the functions since the exceptions raised are also dependent on them.

Regarding the maintainability, probably these should be added right during the addition of the feature to the code base as a practice. And also maybe we can look at some other softwares following these kind of documentation.

These are just my opinions and definitely devs are the best people to comment on this issue.

Cheers.

[raghavrv]

at automated way of finding the raised exceptions

Ummm I don't think we can do that.

The simple way would be to search for .*Error in that function and manually list them.

[raghavrv]

probably these should be added right during the addition of the feature to the code base as a practice

yes.

[maniteja123]

Thanks for all the comments. I understand it is really an additional burden to maintain this and might also add to the lines without actually helping much. But if it is okay, will proceed on adding similarly to other function too ? Thanks.

[raghavrv]

Please confirm with @GaelVaroquaux at #6198 before proceeding

[amueller]

Wait, that's private? Why?

[maniteja123]

Ah sorry got confused with the underscore.

[amueller]

these are all in private functions, so you didn't add anything to the rendered docs btw ....

[maniteja123]

Thanks but I knew that they wouldn't be rendered in the docs. I just thought that it would be helpful to better understand the util functions and also would give an idea on how feasible and useful would this extra section be. Please let me know if you feel this is not an useful addition, will proceed accordingly.

[maniteja123]

Thanks for all the suggestion. Will close this PR for now but will push the changes to this branch in case someone wants to look at it.