tech.ml.dataset icon indicating copy to clipboard operation
tech.ml.dataset copied to clipboard

`ds/concat*` arglist and docstring improvements

Open harold opened this issue 6 months ago • 2 comments

Autocomplete in my editor helpfully offers these suggestions: image

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

  1. mention of the input and output return types
  2. a short working example of usage, so users don't have to wonder if they need to call apply
  3. 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...

harold avatar Aug 20 '24 17:08 harold