Repository: dask/dask

Issue:
Dataframe.set_index docstring might need an update
<!-- Please include a self-contained copy-pastable example that generates the issue if possible.

Please be concise with code posted. See guidelines below on how to provide a good bug report:

- Craft Minimal Bug Reports http://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports
- Minimal Complete Verifiable Examples https://stackoverflow.com/help/mcve

Bug reports that follow these guidelines are easier to diagnose, and so are often handled much more quickly.
-->

**What happened**:

At the time of writting (dask 2.23.0) The `Dataframe.set_index` signature differs from the parameters described in the docstring, it looks like it was originally the `shuffle.py::set_index` docstring but even then it needs an update:
- `drop` parameter is in the signature but not in the doc string
- `other` parameter in the signature corresponds to the `index` parameter in the docstring
- `df` parameter in docstring is actually `self` in the signature
- `compute` in the docstring but actually falls into the `kwargs` parameters
- `**kwargs` parameters could be explained a bit maybe.

**What you expected to happen**:

I would expect the parameter name in the method signature to correspond to the ones in the docstring.

**Minimal Complete Verifiable Example**:

```python
    # method signature
    def set_index(
        self,
        other,
        drop=True,
        sorted=False,
        npartitions=None,
        divisions=None,
        inplace=False,
        **kwargs,
    ):
        """
       ...
        ----------
        df: Dask DataFrame
        index: string or Dask Series
        npartitions: int, None, or 'auto'
        ...
        shuffle: string, optional
        ...
        sorted: bool, optional
        ...
        divisions: list, optional
        ...
        inplace : bool, optional
        ....
        compute: bool
        ...
        Examples
        --------
        ...
        """
```

**Anything else we need to know?**:
I'm willing to update it but I'm not sure what the convention is for documentation in the dask project.

**Environment**:

- Dask version: 2.23.0



Discussion:
Thanks for raising an issue @Timost! Apologies for the delayed response. Indeed, it seems `set_index`'s docstring has gotten out of sync with its signature

>  I'm willing to update it but I'm not sure what the convention is for documentation in the dask project.

Great, thank you! You can check out the Dask contributing docs at https://docs.dask.org/en/latest/develop.html. Specifically, the "Docstrings" and "Contributing to Documentation" will be particularly relevant for this issue 
Thanks for the pointers @jrbourbeau !  I'll go through the doc and try to improve the doc string.

Resolving patch:
diff --git a/dask/dataframe/core.py b/dask/dataframe/core.py
--- a/dask/dataframe/core.py
+++ b/dask/dataframe/core.py
@@ -3665,17 +3665,17 @@ def set_index(
     ):
         """Set the DataFrame index (row labels) using an existing column.
 
-        This realigns the dataset to be sorted by a new column.  This can have a
+        This realigns the dataset to be sorted by a new column. This can have a
         significant impact on performance, because joins, groupbys, lookups, etc.
-        are all much faster on that column.  However, this performance increase
+        are all much faster on that column. However, this performance increase
         comes with a cost, sorting a parallel dataset requires expensive shuffles.
         Often we ``set_index`` once directly after data ingest and filtering and
         then perform many cheap computations off of the sorted dataset.
 
         This function operates exactly like ``pandas.set_index`` except with
-        different performance costs (dask dataframe ``set_index`` is much more expensive).  Under normal
-        operation this function does an initial pass over the index column to
-        compute approximate qunatiles to serve as future divisions.  It then passes
+        different performance costs (dask dataframe ``set_index`` is much more expensive).
+        Under normal operation this function does an initial pass over the index column
+        to compute approximate qunatiles to serve as future divisions. It then passes
         over the data a second time, splitting up each input partition into several
         pieces and sharing those pieces to all of the output partitions now in
         sorted order.
@@ -3683,23 +3683,21 @@ def set_index(
         In some cases we can alleviate those costs, for example if your dataset is
         sorted already then we can avoid making many small pieces or if you know
         good values to split the new index column then we can avoid the initial
-        pass over the data.  For example if your new index is a datetime index and
+        pass over the data. For example if your new index is a datetime index and
         your data is already sorted by day then this entire operation can be done
-        for free.  You can control these options with the following parameters.
+        for free. You can control these options with the following parameters.
 
         Parameters
         ----------
-        df: Dask DataFrame
-        index: string or Dask Series
-        npartitions: int, None, or 'auto'
-            The ideal number of output partitions.   If None use the same as
-            the input.  If 'auto' then decide by memory use.
-        shuffle: string, optional
-            Either ``'disk'`` for single-node operation or ``'tasks'`` for
-            distributed operation.  Will be inferred by your current scheduler.
+        other: string or Dask Series
+        drop: boolean, default True
+            Delete column to be used as the new index.
         sorted: bool, optional
             If the index column is already sorted in increasing order.
             Defaults to False
+        npartitions: int, None, or 'auto'
+            The ideal number of output partitions. If None, use the same as
+            the input. If 'auto' then decide by memory use.
         divisions: list, optional
             Known values on which to separate index values of the partitions.
             See https://docs.dask.org/en/latest/dataframe-design.html#partitions
@@ -3707,14 +3705,19 @@ def set_index(
             that if ``sorted=True``, specified divisions are assumed to match
             the existing partitions in the data. If ``sorted=False``, you should
             leave divisions empty and call ``repartition`` after ``set_index``.
-        inplace : bool, optional
+        inplace: bool, optional
             Modifying the DataFrame in place is not supported by Dask.
             Defaults to False.
-        compute: bool
+        shuffle: string, 'disk' or 'tasks', optional
+            Either ``'disk'`` for single-node operation or ``'tasks'`` for
+            distributed operation.  Will be inferred by your current scheduler.
+        compute: bool, default False
             Whether or not to trigger an immediate computation. Defaults to False.
             Note, that even if you set ``compute=False``, an immediate computation
             will still be triggered if ``divisions`` is ``None``.
-
+        partition_size: int, optional
+            Desired size of each partitions in bytes.
+            Only used when ``npartition='auto'``
         Examples
         --------
         >>> df2 = df.set_index('x')  # doctest: +SKIP


Test patch: