Repository: pandas-dev/pandas

Issue:
read.csv index_col argument accepts string, list-of-string
1. `read.csv` index_col argument has been accepting either string or list-of-string for years, but the doc (as of 0.24 dev) has never been updated to reflect this. Current and suggested text at bottom.
1. All columns used in index_col get dropped as regular columns. The doc never explicitly says this and [it causes user confusion](https://stackoverflow.com/questions/51794078/python-the-label-is-not-in-the-columns-error-after-pd-read-csv-index-col).
1. The doc does however discuss "malformed file with delimiters at the end of each line... you might consider index_col=False", this is overly prominent for a rare defective case and should be shunted somewhere less prominent, or at minimum relegated to a parenthesized footnote.

Current read.csv doc:

> index_col : _int or sequence or `False`, default `None`_
> Column to use as the row labels of the DataFrame. If a sequence is given, a MultiIndex is used. If you have a malformed file with delimiters at the end of each line, you might consider index_col=False to force pandas to not use the first column as the index (row names).

Suggested read.csv doc:

> index_col : _int/string or sequence of int/string or `False`, default `None`_
> Column(s) to use as the row labels of the DataFrame, either given as string name or column index.
> If a sequence of int/string is given, a MultiIndex is used.
> Columns used for the index (row names) are dropped from the actual columns of the input dataframe. (They are accessible via `.index`).
> (Note: `index_col=False` can be used to force pandas to not use the first column as the index, e.g. when you have a malformed file with delimiters at the end of each line).


Discussion:
PRs to improve documentation are always welcome - if you have something you feel is better feel free to submit and the team will provide feedback!
I will take this up.
Can anyone pinpoint the version this was introduced? (at least as old as 0.20.4) and whether it was intentional or accidental?

(I couldn't figure it out from reading through the history and blame on [https://github.com/pandas-dev/pandas/blob/master/pandas/io/parsers.py](https://github.com/pandas-dev/pandas/blob/master/pandas/io/parsers.py))

Resolving patch:
diff --git a/pandas/io/parsers.py b/pandas/io/parsers.py
--- a/pandas/io/parsers.py
+++ b/pandas/io/parsers.py
@@ -102,11 +102,14 @@
     List of column names to use. If file contains no header row, then you
     should explicitly pass ``header=None``. Duplicates in this list will cause
     a ``UserWarning`` to be issued.
-index_col : int, sequence or bool, optional
-    Column to use as the row labels of the DataFrame. If a sequence is given, a
-    MultiIndex is used. If you have a malformed file with delimiters at the end
-    of each line, you might consider ``index_col=False`` to force pandas to
-    not use the first column as the index (row names).
+index_col : int, str, sequence of int / str, or False, default ``None``
+  Column(s) to use as the row labels of the ``DataFrame``, either given as
+  string name or column index. If a sequence of int / str is given, a
+  MultiIndex is used.
+
+  Note: ``index_col=False`` can be used to force pandas to *not* use the first
+  column as the index, e.g. when you have a malformed file with delimiters at
+  the end of each line.
 usecols : list-like or callable, optional
     Return a subset of the columns. If list-like, all elements must either
     be positional (i.e. integer indices into the document columns) or strings


Test patch: