DOC: update the pandas.DataFrame.to_string docstring
State: closed

Had to correct parameters descriptions in common docstrings (format.py) as well as in frame.py.

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

- [x] PR title is "DOC: update the <your-function-or-method> docstring"
- [x] The validation script passes: `scripts/validate_docstrings.py <your-function-or-method>`
- [x] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [x] The html version looks good: `python doc/make.py --single <your-function-or-method>`
- [x] It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

```
################################################################################
#################### Docstring (pandas.DataFrame.to_string) ####################
################################################################################

Render a DataFrame to a console-friendly tabular output.

Convert DataFrame object into a string (or unicode) representation
which can be shown in command line interface.

See Also
--------
pandas.DataFrame.to_html
    Convert dataframe to a html file.

Examples
--------
>>> d = {'col1' : [1, 2, 3], 'col2' : [4, 5, 6]}
>>> df = pd.DataFrame(d)
>>> print(df.to_string())
   col1  col2
0     1     4
1     2     5
2     3     6

Parameters
----------
buf : StringIO-like, optional
    Buffer to write to.
columns : sequence, optional, default None
    The subset of columns to write. The default None writes all columns.
col_space : int, optional
    The minimum width of each column.
header : bool, optional
    Write out the column names. If a list of strings is given, it is assumed to be aliases for the column names.
index : bool, optional, default True
    Whether to print index (row) labels.
na_rep : str, optional, default 'NaN'
    String representation of NAN to use.
formatters : list or dict of one-param. functions, optional, default None
    Formatter functions to apply to columns' elements by position or name.
    The result of each function must be a unicode string.
    List must be of length equal to the number of columns.
float_format : one-parameter function, optional, default None
    Formatter function to apply to columns' elements if they are floats.
    The result of this function must be a unicode string.
sparsify : bool, optional, default True
    Set to False for a DataFrame with a hierarchical index to print every
    multiindex key at each row.
index_names : bool, optional, default True
    Prints the names of the indexes.
line_width : int, optional, default no wrap
    Width to wrap a line in characters.
max_rows : int, optional
    Maximum number of rows to display in the console.
max_cols : int, optional
    Maximum number of columns to display in the console.
show_dimensions : bool, default False
    Display dataframe's dimensions (number of rows by number of columns).

justify : str, default None
    How to justify the column labels. If None uses the option from
    the print configuration (controlled by set_option), 'right' out
    of the box. Valid values are

    * left
    * right
    * center
    * justify
    * justify-all
    * start
    * end
    * inherit
    * match-parent
    * initial
    * unset.

Returns
-------
formatted : str (or unicode, depending on data and options)

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.DataFrame.to_string" correct. :)
```

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.


Checklist for other PRs (remove this part if you are doing a PR for the pandas documentation sprint):

- [ ] closes #xxxx
- [ ] tests added / passed
- [x] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] whatsnew entry


Labels:
name: Docs

Comments:
Hi,

I have a bit of a problem here as the docstring for this method is a result of concatenation of common docstrings, method’s docstring and a return docstring.
Therefore it looks like it is missing some parts or they are not in the right order but I believe the deciding factor here should be the actual html built by sphinx and it looks ok to me.
I shall add a return description though and recheck this again and post a result of html build by sphinx to confirm the final result.
Thx for reviewing.
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20173?src=pr&el=h1) Report
> Merging [#20173](https://codecov.io/gh/pandas-dev/pandas/pull/20173?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/5380fcd4485498ea54210cf9e26fc5000a3d8555?src=pr&el=desc) will **decrease** coverage by `<.01%`.
> The diff coverage is `100%`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/20173/graphs/tree.svg?width=650&height=150&src=pr&token=eZ4WkYLtcO)](https://codecov.io/gh/pandas-dev/pandas/pull/20173?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##           master   #20173      +/-   ##
==========================================
- Coverage    91.9%    91.9%   -0.01%     
==========================================
  Files         160      160              
  Lines       49892    49891       -1     
==========================================
- Hits        45852    45851       -1     
  Misses       4040     4040
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.28% <100%> (-0.01%)` | :arrow_down: |
| #single | `42.1% <100%> (-0.01%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20173?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/io/formats/format.py](https://codecov.io/gh/pandas-dev/pandas/pull/20173/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2Zvcm1hdHMvZm9ybWF0LnB5) | `98.24% <100%> (-0.01%)` | :arrow_down: |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/20173/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.19% <100%> (ø)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20173?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20173?src=pr&el=footer). Last update [5380fcd...bef020a](https://codecov.io/gh/pandas-dev/pandas/pull/20173?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

As an attachement there is a zipped html rendering of the command:
python make.py html --single pandas.DataFrame.to_string 
for modified docstring for pandas.DataFrame.to_string.


[pandas.DataFrame.to_string.zip](https://github.com/pandas-dev/pandas/files/1808817/pandas.DataFrame.to_string.zip)

It looks ok to me.
We have to remember that under the method itself there will be only See Also and Examples as the rest is pulled automatically from the common docstrings in format.py.


Taking a look at this one!
Ended up being a rather complicated fixup - @datapythonista could use a second set of eyes if you have time
Thanks @Tomasz-Kluczkowski !