Optional args style

[kescobo]

This is the second of 3 PRs replacing #2488 now that the big reorg has happened. These should not change or add any functionality, but are instead intended to unify some style conventions.

Here, I deal with optional arguments in docstrings. There isn't a strong convention here - I looked through Base docstrings, and their style is inconsistent as well. One thing that does seem consistent is that multiple optional arguments have nested brackets, eg [, opt1[, opt2] ]. There aren't many examples in this package, but the principle I went with is that everything that is optional (including separators and spaces) should be inside brackets. So eg

foo(required[, opt])
bar([opt, ]required)

For multiple optional args, I did the same thing, with nested brackets. One thing that may or may not be controversial is that I put spaces between closing brackets.

baz(required[, opt1[, opt2] ])

There are examples and counterexamples of all of these things in Base, and I could not find a style guide that specifies (here's the section in blue style as example).

[bkamins]

Looks good. Can you please check if https://github.com/JuliaData/DataFrames.jl/blob/master/CONTRIBUTING.md has an appropriate rule mentioned (so that we collect the style recommendations there).

[kescobo]

Can you please check if https://github.com/JuliaData/DataFrames.jl/blob/master/CONTRIBUTING.md has an appropriate rule mentioned (so that we collect the style recommendations there).

I was about to push the 3rd one. Rule about spaces is already there, can I include this and the one about zeros in floats in the same PR to avoid test churn? (it will also avoid merge conflict)

[kescobo]

Might also be useful to settle on language before pushing. I was thinking

* In docstrings, optional arguments, including separators and spaces, are surrounded by brackets, 
  e.g. `mymethod(required[, optional1[, optional2] ]; kwargs...)`

[bkamins]

can I include this and the one about zeros in floats in the same PR to avoid test churn? (it will also avoid merge conflict)

OK

Might also be useful to settle on language before pushing

Looks good to me

[bkamins]

Thank you!