Improve docstrings

[kjordahl]

Some docstrings are missing, some are fairly rudimentary. All modules, classes, methods and functions should have useful docstrings.

[souravsingh]

I would like to work on this issue.How Do I work on it?

[jorisvandenbossche]

@souravsingh For how docstring should look like, you can look at existing docstring, and also take a look at the specification of the Numpy docstring standard: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt for an explanation of the syntax and the different sections.

Then I would say, go through the different methods/classes of geopandas and see if there are ones were a full docstring is lacking, and try to add an explanation of the parameters, add an example, ..

[kjordahl]

@souravsingh Here's one example: The plot() method of a GeoDataFrame has no docstring at all. It just calls plot_dataframe() function (which has a decent docstring), so it takes the same options. As a consequence, currently a user in IPython can't get useful help from GeoDataFrame.plot?, you can't build complete API documentation, and so on.

There are a few options to fix this example:

• We could add a short docstring to the plot() method, referring users to plot_dataframe() for the complete options.
• We could copy the docstring from plot_dataframe(), adjusting as necessary. This has the drawback of adding a maintenance burden of keeping the options up-to-date in two independent places. I would prefer not to do this if possible.
• We could define the docstring (or a subset) in one place, and alter the __doc__ attribute of the class to add the appropriate common parts. This is probably manageable if they are identical, but a bit trickier if is mix-and-match. I think it can work in this case. In more complicated cases, it could impair the readability of the code.

There are other missing and incomplete docstrings in the code, and the tradeoffs between these options may be slightly different in other cases.

Thanks for helping out!

[jorisvandenbossche]

@kjordahl even another option is to define GeoDataFrame.plot = plot_dataframe. In this way, the docstring is automatically used (as well as the keyword inspection, instead of the **kwargs now). This is also how pandas does it: https://github.com/pydata/pandas/blob/v0.16.2/pandas/core/frame.py#L5138

[martinfleis]

Closed by recent documentation enhancements.