Document purpose for all assertion methods

[csparpa]

Each assertion method should clearly document its purpose.

As the return values for each assertion method can either be the Check object instance itself or an exception and each method takes no parameter, docs are straightforward to write.

This is the first step towards having an automated documentation system - eg. see Sphinx setup on my other projects PyOWM or Baroque.

Example

Instead of:

def is_not_complex(self):
    try:
        assert not isinstance(self._val, complex)
        return self
    except AssertionError:
        raise CheckError('{} is complex'.format(self._val))

it would be nice to have

def is_not_complex(self):
    """
    Checks that the argument is not a complex number

    :returns: the self `fluentcheck.Check` instance if assertion succeeds
    :raises: `fluentcheck.CheckError` if assertion fails

    """
    try:
        assert not isinstance(self._val, complex)
        return self
    except AssertionError:
        raise CheckError('{} is complex'.format(self._val))

[hedyhli]

Interesting, in that case I guess those assertion methods doc string going to be really similar (because of the raises and return)

[hedyhli]

Looking into this... I think the tests should also have docstr

[deanagan]

Thanks Hedy. The tests can have them too. I wonder if existing documentation tools can automate the docstring generation.

[hedyhli]

Not that I know of, but maybe a small script can do it (to automate inserting :raises:, and :return: lines), and by the way interrogate can help to look for missing doc strings

[csparpa]

@hedythedev @deanagan this might help: https://stackoverflow.com/questions/37549741/is-it-possible-to-bulk-add-docstrings-to-all-the-functions-in-pycharm

[hedyhli]

I don’t use PyCharm, but vim-pydocstring should bulk add them for me 😄