add cols to describe

[bkamins]

Fixes #2014

I have also tried to improve docs a bit.

[nalimilan]

Thanks. Just to be sure, do you think this keyword argument could apply to other functions?

[nalimilan]

Shouldn't we just drop this (in another PR)? Clearly if you pass io you expect the result to be printed there, so it's actively misleading not to throw an error. Or the method taking io should call show(io, describe(...)).

Anyway when moving things from StatsBase to Statistics I'd like to change that API so that describe always returns a special object that can be printed, instead of printing the result directly. That's more useful and more standard.

[bkamins]

100% agreed in all you write - passing io made no sense to me here, but it was defined in DataAPI.jl and I did not want to make breaking changes in this PR.

So - after merging this PR do we make another PR that deprecates io? (this is what I would do in DataFrames.jl; all other actions are needed in other packages, but they can be done independently, as we clearly document how describe with AbstractDataFrame works).

[nalimilan]

Right, I think we can start changing this in DataFrames, the StatsBase to Statistics move will take longer.

[bkamins]

Just to be sure, do you think this keyword argument could apply to other functions?

I am not fully clear what you have in mind.

Do you mean that cols keyword argument could be used similarly in other functions?
If this is a question then my thinking is that the answer is "yes", and mostly we use cols kwarg, or a positional argument that is also called cols to achieve this effect. We could change all occurrences of positional argument to a kwarg in places where it would make sense. Was this the question?

[nalimilan]

I guess my question was relatively broad: do we anticipate adding the cols keyword argument to other functions? should we switch some/all functions from positional to keyword for cols?

[bkamins]

Here we have to use cols as kwarg as positional args are used for other purpose.

For sure I would use cols consistently as positional or kwarg in all functions. Now the question what to prefer - this is something I am not 100% sure - here I really do not understand how e.g. in Base this decision is made and what are the rules.

For sure in most functions we allow cols as positional argument in DataFrames.jl.

If the general rule is "use positional argument if there are few of them and kwarg if there are many of them" than I would not change anything in other functions, but I am not sure if this is the rule 😢.

[bkamins]

@nalimilan - so do you have an opinion how we should proceed.

I believe that in this PR the valid approach is to have cols as kwarg. I have run a quick query and I think that everywhere else cols is a positional arg.

[nalimilan]

Sounds good. Maybe the main question is actually whether we should switch similar functions to a keyword argument, e.g. allowmissing.