Add validation for optional parameters

[MatthewFlamm]

This PR adds validation check for optional parameters. If an optional parameter exists in the signature of a function, the documentation is checked for one of three options in the 'type':

1. Use of optional
2. Use of default
3. Use of {'option1', 'option2'}

Related to #367.

[MatthewFlamm]

I think there should also be the inverse check to what has been implemented, i.e. if a parameter is documented as optional/default then check that the parameter has a default in the signature. However, it isn't super clear to me with the usage of the set-like notation.

Set-like notation [my terminology] is described as:

When a parameter can only assume one of a fixed set of values, those values can be listed in braces, with the default appearing first:

I haven't done a survey yet, but I heavily suspect that users may also be using this for 'fixed set of values' but without a default.

Edit: I have implemented the reverse check but not when the set-like notation is used.

[rossbar]

I think this is too strict of an interpretation of "optional".

For example, it is quite common to use mykwarg=None to indicate some form of default behavior, in which case I think it's safe to call mykwarg "optional". In this case however, just because a is a keyword argument does not necessarily mean that it's optional. For example, if a=None would raise an exception (e.g. as might be expected in the head1 function above) then I don't think it's necessarily correct to call the a kwarg "optional".

In other words, I think there needs to be a little more discussion in determining what "optional" really means in the context of the docstring standard, and if there's a distinction between optional/non-optional kwargs. I suspect that some projects do make such a distinction in their documentation.

[MatthewFlamm]

This implementation would treat mykwarg=None as an optional parameter too. I can add a test here to ensure this.

These meet the definition of optional in that users can opt to not provide it. There is no guarantee that this is a suitable choice when it is optional. In my opinion, if the function raises an error based on a default value, then this should be documented, probably in the Raises section.

I welcome a discussion on this, should it be here or in a separate issue?

[MatthewFlamm]

I think it is also important that projects can turn off this check if they have specific requirements where a parameter is optional in its signature but not optional in implementation. It should be more common to have have the signature match the implementation requirement.

[MatthewFlamm]

As evidence of usefulness of this check, I ran this branch (using 3ac46bf) against https://github.com/pyvista/pyvista repo and found well over 50 parameters that were incorrectly documented with respect to the optionality of the parameter. In a non-random sampling, they were all true positive IDs. See pyvista/pyvista#3347.