tech.ml.dataset
tech.ml.dataset copied to clipboard
`ds/concat*` arglist and docstring improvements
Autocomplete in my editor helpfully offers these suggestions:
The docstring for ds/concat
says this:
Concatenate datasets in place using a copying-concatenation.
Which I find sort of confusing given that the three functions concat
, concat-inplace
, and concat-copying
seem to imply that in place and copying are different.
Improve arglists
Also, the arglist of all three functions is: [dataset & args]
, which sort of obscures the fact that you're supposed to pass in many arguments each a dataset. Would [& datasets]
be better? ... clojure.core/concat
has [x y & zs]
which I also sort of don't like because it obscures the fact that the arguments are supposed to be sequences.
Improve docstrings
My proposal would be for re-written docstrings on all three of these functions with
- mention of the input and output return types
- a short working example of usage, so users don't have to wonder if they need to call
apply
- an indication in all three to which one is the one you probably want (is it
ds/concat
?) with a short explanation of why you occasionally might want the other two, with, if possible, a short example of their ideal use...