Alex Miller <a...@puredanger.com> writes:
> On Monday, September 25, 2017 at 11:42:12 AM UTC-5, Phillip Lord wrote:
>> Clojure's doc strings, though, contain knowledge that is not
>> clear. Consider, this documentation:
>>
>> Returns a new seq where x is the first element and seq is the rest.
>>
>> x is the name of a parameter. So is the the second occurence of seq, but
>> not the first. Neither first, nor rest refer to the functions in
>> clojure.core, although both probably should do.
>>
>
> You didn't mention it but this is the docstring for cons. You also stripped
> half the context (the arglist):
>
> -------------------------
> clojure.core/cons
> ([x seq])
> Returns a new seq where x is the first element and seq is
> the rest.
>
> To me, first and rest here are clearly referring to the English meaning,
> not the functions, but also intentionally echoes the actual function names
> which can be used to extract x and seq. I think that's all good.
Yes, I agree with first and rest. But you are inferring this. A tool
will not.
> You can go further with echoing the first/rest stuff by using a spec
> with a :fn too:
>
> -------------------------
> clojure.core/cons
> ([x seq])
> Returns a new seq where x is the first element and seq is
> the rest.
> Spec
> args: (cat :x any? :seq seqable?)
> ret: seq?
> fn: (fn [{:keys [args ret]}] (and (= (:x args) (first ret)) (= (sequence
> (:seq args)) (rest ret))))
>
> I think this is way better in specifying the args and ret and actually
> includes a very precise description of how the args and return value relate
> to first and ret.
Yep. Precise, but not very readable.
>> Compare this to the documentation for "apply" from Andy Fingerhuts
>> thalia.
>>
>
> It seems weird to me to give the docstring from cons above and then from
> Andy's apply below as a comparison.
Thalia is nice but, alas, not comprehensive.
> I do think it would be useful if the docstring for apply said that args had
> to be seqable. Of course, if apply had a spec, you'd have that:
>
> user=> (s/fdef clojure.core/apply :args (s/cat :f ifn? :prepend (s/* any?)
> :args seqable?))
> clojure.core/apply
> user=> (doc apply)
> -------------------------
> clojure.core/apply
> ([f args] [f x args] [f x y args] [f x y z args] [f a b c d & args])
> Applies fn f to the argument list formed by prepending intervening
> arguments to args.
> Spec
> args: (cat :f ifn? :prepend (* any?) :args seqable?)
> ret: any?
>
> Some slight alterations in the :arglists, :doc, and spec names could align
> these even better.
Indeed, this would be a nice addition.
> Examples:
>> ```clojure\nuser=> (apply + [1 2]) ; same as (+ 1 2) 3
>> user=> (apply + 1 2 [3 4 5 6]) ; same as (+ 1 2 3 4 5 6)
>>
>
> I think one example in this docstring would actually say a lot. I don't
> like the formatting here (why the clojure? why the user prompt? why the
> dangling 3?).
The formatting is mine -- I converted the newline chars from the
string. The 3 is my mistaken transcription.
>> It would be possible to go even further than this; consider the runnable
>> doc strings of rust -- the examples are also tests. Emacs' dash.el does
>> the same thing.
>>
>
> Cool idea. As I showed above, we're 95% of the way there already, but with
> *automatically generated examples*. Although hand-picked ones would
> undoubtedly serve as better examples, but you could actually inject custom
> arg generators to even handle that.
As you say, hand-picked ones would be better -- documentation is not the
same thing as a test. Rather, it is good to be able to test the
documentation.
Why not ensure that the right thing (hand-picked examples) are
supported first? Automatically generated examples can come later.
Still, it is good to know that these things are being actively worked
on. The documentation has been static for a long time, and improvements
would be gratefully recieved.
Phil
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@googlegroups.com
Note that posts from new members are moderated - please be patient with your
first post.
To unsubscribe from this group, send email to
clojure+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
---
You received this message because you are subscribed to the Google Groups
"Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
