add data_columns to doc string
State: closed

- [x] closes #13061 
- [ ] tests added / passed
- [x] passes `git diff upstream/master | flake8 --diff`
- [ ] whatsnew entry

How about this for #13061 ?
I don't think pandas has tests for each documented field, correct?
Do you want a whatsnew entry for this? If yes, how does that work? The guidelines don't talk about that.


Labels:
name: Docs

Comments:
> > > I don't think pandas has tests for each documented field, correct?

not sure what you mean by this. pandas has tests for each option of course. doc-strings in the past were not audited as much as currently.

The doc-string should match for the same keyword args. Please change to match.

```
In [1]: pd.HDFStore.append?
Signature: pd.HDFStore.append(self, key, value, format=None, append=True, columns=None, dropna=None, **kwargs)
Docstring:
Append to Table in file. Node must already exist and be Table
format.

Parameters
----------
key : object
value : {Series, DataFrame, Panel, Panel4D}
format: 'table' is the default
    table(t) : table format
               Write as a PyTables Table structure which may perform
               worse but allow more flexible operations like searching
               / selecting subsets of the data
append       : boolean, default True, append the input data to the
    existing
data_columns : list of columns to create as data columns, or True to
    use all columns
min_itemsize : dict of columns that specify minimum string sizes
nan_rep      : string to use as string nan represenation
chunksize    : size to chunk the writing
expectedrows : expected TOTAL row size of this table
encoding     : default None, provide an encoding for strings
dropna       : boolean, default False, do not write an ALL nan row to
    the store settable by the option 'io.hdf.dropna_table'
Notes
-----
Does *not* check if data being appended overlaps with existing
data in the table, so be careful
File:      ~/pandas/pandas/io/pytables.py
Type:      instancemethod
```

1. Do you want me to expand the docstring in `.append()`? Or want it in `.to_hdf()` as short as it is in `.append()`
2. I cannot find anywhere `to_hdf` tests that test for it's individual options. Only mentioning of to_hdf I can find is [here](https://github.com/pydata/pandas/blob/65ed3afd092908130905e7d86ff1b6b9c2002d00/pandas/io/tests/test_pytables.py#L211-L238).

`to_hdf` just calls the underlying functions it's all tested directly on `HDFStore`. `to_hdf` is just a wrapper around this.

you can expand the `.append` doc string if u want and add that to `to_hdf`

I just noticed that columns in HDFStore.append() is not supported anymore:

``` python
        if columns is not None:
            raise TypeError("columns is not a supported keyword in append, "
                            "try data_columns")
```

Should the `append=None` not be removed then from the call signature?

@michaelaye what does `columns` have to do with `append`? (that is an older / deprecated kw)

That's how it looks like, yes. But it's still there, in the method signature, see above, where you copied it in yourself.

## [Current coverage](https://codecov.io/gh/pydata/pandas/pull/13065?src=pr) is **84.14%**

> Merging [#13065](https://codecov.io/gh/pydata/pandas/pull/13065?src=pr) into [master](https://codecov.io/gh/pydata/pandas/branch/master?src=pr) will decrease coverage by **<.01%**

``` diff
@@             master     #13065   diff @@
==========================================
  Files           138        137     -1   
  Lines         50587      50261   -326   
  Methods           0          0          
  Messages          0          0          
  Branches          0          0          
==========================================
- Hits          42593      42288   -305   
+ Misses         7994       7973    -21   
  Partials          0          0          
```

> Powered by [Codecov](https://codecov.io?src=pr). Last updated by [b4e2d34...8a36c36](https://codecov.io/gh/pydata/pandas/compare/b4e2d34edcbc404f6c90f76b67bcc5fe26f0945f...8a36c3649ddd3ec3cef4d03ef3d747dc4107a231)

What about the obsolete "columns" keyword in the Store.append call()? Different problem I guess, but I don't really understand why to keep it? Not at least for backwards compatibility, because it raises a TypeError now, and so it would if the keyword would be removed and somebody still would try to use it.

its to provide a custom message with a hint, meaning `columns` was passed, but maybe you meant `data_columns`.

`columns` is a valid kw for `.select`, so people might try it with append.

This looks good to me. @jreback ?

can you rebase / update?

I see the problem now, maybe this is the reason why the docstring was left out in the first place? What should I do? I guess the `data_columns` option as actually being ignored if it would be used with a Series.to_hdf? I just tried to use it with a non-existing column name and no error appeared.

can you update

I repeat my previous question from May 25 (under the code discussion at the change overview), for which I still am waiting for guidance:

"So, for a Panel I actually can not add columns to the index?
If that's true, how about then I add the docstring like so:

```
data_columns : only applicable to DataFrames, see examples
```

and then I add the usage examples with the suggestions you made above?

@michaelaye I dont' think can use a shared doc here as this is a doc-string on the class (and not on an object yet). So put a more general doc-string should be enough (e.g. give an example for series, dataframe, panel for which axes you can use).

@michaelaye I cherry-picked your commit to combine it with the changes of the other merged PR

-> rebased in #14046