DOC: update docstring of DataFrame.append

[jorisvandenbossche]

I always thought that append was for appending rows, not columns. So, unless I am completely missing something, the docstring was saying the wrong thing.

So I reworded it a bit, see below.
Apart from that, there were some other things that are not fully clear to me in the docstring:

• The docstring says that other should be a "list of Series/dict-like objects" (or a Dataframe):
  • Does it need to be a list? It also works with just a Series. Or what are the differences between both?
  • With a simple example, I don't see a difference, although in implementation, there is.
• The docstring says for the ignore_index kwarg: "Useful for gluing together record arrays"
  • How does this look in practice? If I try to append a record array, I get "TypeError: cannot concatenate a non-NDFrame object" -> so I will remove this

[jreback]

see #8295 / #8337

the axis argument should be added to append to make this symmetric with concat.

The reason for the accepting of say a list is that if it can be interpreted correctly in the context of a Dataframe (e.g. it matches the columns and can be directly converted; this is NOT true for concat).

I don't know about record arrays, that may be a 'feature' that was not implemented.

[jorisvandenbossche]

I updated this (for how the function now is, so without the axis argument). Only the first sentence (about adding rows) will have to be reverted when the other PR is rebased/merged

Removed the sentence about record arrays (does not make sense as far as I can see)
Added a see also and example, and some other small things.

[TomAugspurger]

👍

[jreback]

@jorisvandenbossche lgtm