DOC: add proper docstrings and documentation to refguide-check

[mattip]

tools/refguide-check.py needs work documenting the functions. xref gh-14732.

This file is not shipped with NumPy and does not appear on the numpy.org website, but still should be properly documented.

[san7988]

Hi,

is this complete?

Thanks

[eric-wieser]

Unless you can see a PR linked either in a comment or a cross reference, then a safe assumption is to assume not.

So no, this still needs doing :)

[san7988]

Sorry but I'm a newbie to OS so please bear with me.
I went through issue #14732 to understand the issue more.

I just wanted to understand this issue clearly so please help me with that.
The above mentioned file has some methods with docstrings and some without them. So we need to add documentation to methods missing docstrings. Is my understanding right?

Thanks

[mattip]

The idea is to use the numpydoc docstring standard to document at least the higher-level functions: main, check_items, check_rst, check_doctests, and perhaps one level lower.

[san7988]

So if we take an example, in method check_doctests we have currently:
def check_doctests(module, verbose, ns=None, dots=True, doctest_warnings=False):
"""Check code in docstrings of the module's public symbols.
Returns: list of [(item_name, success_flag, output), ...]
"""

should be something like:

"""
Check code in docstrings of the module's public symbols.

Returns
--------
result : list of [(item_name, success_flag, output), ...]
"""

Is that correct?

[mattip]

Correct, as well we should document the parameters

[san7988]

Cool. I'm on it.
Thanks

[san7988]

Hi,

I have done changes. Should I go ahead and create the PR?

[mattip]

Yes. Please take a look at the developer workflow around working with git and making a PR.