issue_comments

Maybe we keep it focused on one issue, but another oddity — JupyterLab seems to list the signature as xr.Dataset(*args, **kwds), but the signature is explicit: https://github.com/pydata/xarray/blob/v0.16.0/xarray/core/dataset.py#L468-L475

I don't think it's unusual to document constructor parameters on __init__. For example, that's the recommendation of the Google Python style-guide, followed by most Google Python projects (e.g., TensorFlow). So I think Spyder would be improved by documenting __init__, too.

That said, I don't have any principled reason for deviating from the NumPy docstring standards here. I also agree that the Dataset constructor would be improved by adding usage examples of how to create a Dataset.

Thanks @keewis , good spot.

That looks right @Illviljan , so unless there's other information, it looks like we should move it to the class.

Is there any reason to keep it on the __init__?

Creating a decorator for this sounds a bit too fancy compared to just moving the init docstring to the class docstring in my opinion.

Is xarray following the numpy docstring guidelines? Reading up on the numpy guidelines they recommend that the constructor (init) should be documented at the class docstring. https://numpydoc.readthedocs.io/en/latest/format.html#class-docstring

And after looking around some more the modules that prefers having init parameters at the class docstring are: * numpy - https://github.com/numpy/numpy/blob/master/numpy/core/records.py#L98 * scipy - https://github.com/scipy/scipy/blob/v1.5.2/scipy/interpolate/interpolate.py * pandas - https://github.com/pandas-dev/pandas/blob/v1.1.0/pandas/core/frame.py#L339-L9257 * dask - https://github.com/dask/dask/blob/master/dask/blockwise.py#L135

python -m pydoc xarray.Dataset displays __doc__ and then all methods / attributes / properties and their __doc__, so that's not a problem there. As @Illviljan pointed out, ipython / jupyter display the docstring of Dataset.__init__ as a special Init docstring section.

So I guess this is a "bug" in spyder (and maybe also other IDEs?), but we could work around that using a decorator.

My opinion is that it is a general issue but maybe that's because I prefer Spyder? Jupyterlab is the other IDE I know that has this functionality it seems to print class and init information. Are there any others?

Checking pd.DataFrame() in JupyterLab:

Checking xr.Dataset() in JupyterLab:

Any idea whether this is a Spyder issue only or more general?

Yeah, I've read the same thing that either __init__ or the class can be used. I liked adding it in __init__ too when I've developed classes because it's consistent with other functions and methods. But now that I'm on the user side I think the class docstring is the way to go. Pandas and scipy seems to be pretty consistent with this as well: * Series - https://github.com/pandas-dev/pandas/blob/v1.1.0/pandas/core/series.py#L139-L4979 * Interpolate- https://github.com/scipy/scipy/blob/v1.5.2/scipy/interpolate/interpolate.py

The Spyder help pane simply reads xr.Dataset.__doc__ and it would correctly read the __init__ doc if I I typed out xr.Dataset.__init__ too, but which users prefers to do that?

Thanks for the feedback; I agree there's more to initializing a Dataset than a DataFrame, and we should make the docs as accessible as possible.

In this specific case, is this a Spyder issue only or more general? IIUC using the __init__ or the class are both standard for the class docstring