Re: Clojure core documentation

[Didier]

At first I thought the doc was really complicated and hard to understand, 
and then I became more familiar with FP and Clojure, and now I think the 
doc is perfect, sweet, short and to the point.

What happens with a lot of those higher order functions is that you really 
don't understand them until you see examples and try them out. To which 
clojuredocs.org has been invaluable to me. I don't think any amount of 
rewording would help. Examples and trying them out is all that really makes 
it click. Would be cool to either add clojuredocs like functionality to 
clojure.org, and/or have clojure.repl/doc or another fn in there pull down 
examples and notes from clojuredoc.org.

On Monday, 25 September 2017 15:15:45 UTC-7, Alex Miller wrote:
>
>
>
> 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. 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. And you can property test it with stest/check!
>  
>
>> 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.
> For actual comparison the docstring of 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.
>
>  
>
>> `f` is a function and the last argument `args` is a sequence.  Calls  
>
> this is wrong, should be something seqable  --^
> see:  (apply vector 1 "abc")  ;; [1 \a \b \c]
>
> 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.
>
> `f` with the elements of `args` as its arguments.  If more arguments 
>> `x`, `y`, etc.  are specified, they are added to the beginning of 
>> `args` to form the complete argument list with which `f` is called. 
>>
>
> I find this confusing in that it starts with the beginning and end and 
> then talks about the middle and prefer the original, but matter of taste I 
> suppose. I'd take the spec over either.
>
> 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?). Could actually use the spec to generate as many examples as 
> you like though using s/exercise-fn!
>
> user=> (s/exercise-fn 'clojure.core/cons)
> ([(nil "") (nil)] 
> [(() "") (())] 
> [(nil nil) (nil)] 
> [(nil {Hr-* -1.0, false #uuid "bf1314cc-f950-4a52-969b-45023fc5cd13"}) 
> (nil [Hr-* -1.0] [false #uuid "bf1314cc-f950-4a52-969b-45023fc5cd13"])] 
>
> etc etc - make as many as you like. You would want to format these instead 
> (bike shed away):
>
> (cons nil "") ;; => (nil)
> (cons () "") ;; => (())
> (cons nil nil) ;; => (nil)
> etc
>  
>
>>
>> Which is essentially superior in every 

Re: clojure.core.server/start-server should have :encoding as option

[Andy Fingerhut]

And if you need specific instructions on filing an issue in JIRA, here they
are:

If you want to be able to create or edit JIRA tickets, create an
account by going to this page:

https://dev.clojure.org/jira/secure/Signup!default.jspa

The link below gives a brief introduction to the process of creating
tickets and submitting patches to Clojure and its contributed
libraries:

https://dev.clojure.org/display/community/Contributing+FAQ

It contains some links to pages with further details, but the one
below is a good link to bookmark if you want to get to just about
anywhere related to Clojure contribution and development:

https://dev.clojure.org/display/community/Contributing

Andy Fingerhut


On Sun, Sep 24, 2017 at 8:50 AM, Alex Miller  wrote:

> File a jira
>
> --
> 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.
>

-- 
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.

Re: Clojure core documentation

[Phillip Lord]

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.

Compare this to the documentation for "apply" from Andy Fingerhuts
thalia.

`f` is a function and the last argument `args` is a sequence.  Calls
`f` with the elements of `args` as its arguments.  If more arguments
`x`, `y`, etc.  are specified, they are added to the beginning of
`args` to form the complete argument list with which `f` is called.

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)

Which is essentially superior in every way. The existence of neither
specs nor clojure.org don't really change this.

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.

Still, it's been this way since I first started using clojure (1.3/1.4)
so I suspect that it's not going to change.

Phil



Stuart Halloway  writes:

> Clojure has great data, and great metadata. Documentation strings are *not*
> great data, they are strings.
>
> If you want to provide more structured support than docstrings to help
> someone use Clojure, look at specs for inspiration. They are made of data,
> and they live in a registry separate from Clojure's var system. This kind
> of decoupling supports composition and tooling without requiring any
> addition or change to Clojure.
>
> I would also echo Matching Socks: Having more and better guides at
> clojure.org would be great. The contribution process is described at
> https://github.com/clojure/clojure-site/blob/master/content/community/contributing_site.adoc
> .
>
> Regards,
> Stu
>
> On Mon, Sep 11, 2017 at 5:23 AM, Matching Socks 
> wrote:
>
>> I am not convinced I would have found the API docs on reducers or zippers
>> more informative if all references had been tidily markdown'ed.
>>
>> The new clojure.org welcomes contributions of topical overviews.  That's
>> helpful.
>>
>> But, to interpret docstrings, nothing helps like perspective.  The thing
>> about perspective is that there could be so many.  I like "Clojure
>> Programming" by Emerick, Carper & Grand.

-- 
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.

Re: Is it wrong that I'm thinking about this?

[Colin Fleming]

I'm pretty sure you can't use a bare colon - Clojure will attempt to read
it as a keyword and will fail since there's nothing following. :- is just a
normal keyword.

I think you can take the minimalist syntax too far, if there were no
separator at all then you'd have to be counting elements to see which was
the type and which was the param. This works for let and other similar
forms, but their elements are generally aligned vertically so it's usually
very clear which is which; this is usually not the case for parameters.

On 25 September 2017 at 18:34, Didier  wrote:

> Agree, but I'm not a huge fan of :- as the syntax. Its fine, but why not
> just colon like in pascal based languages?
> Or even just have the spec follow the arguments and the arg list?
>
> I think for spec, macros of a different name might be best, since I think
> its not useful to have fns that don't have all its args specced and its
> return argument specced.
> So I think it would make more sense to choose to either spec fully or not.
> Only the fn-spec should be optional.
> If you do so, then you can use generative testing and instrumentation, and
> maybe even run spectrum static checks.
>
> My 2 cents.
>
> On Sunday, 24 September 2017 10:34:22 UTC-7, Tommi Reiman wrote:
>>
>> Would also love to see the spec-aware fn, def, defn and defrecord utils
>> somewhere. One thing I like most about Clojure(Script) is it's conciseness
>> and Schema provided just that with it's schema-aware def(n)s & the plumbing
>> defnk. The current fdef seems good for libraries, but feels noisy for
>> apps.
>>
>> Some related links:
>>
>> - https://github.com/plumatic/schema#beyond-type-hints
>> - https://github.com/gfredericks/schpec/blob/master/src/com/
>> gfredericks/schpec/defn%2Bspec.clj
>> - https://github.com/plumatic/schema/issues/366
>> - https://github.com/metosin/spec-tools/issues/72
>>
>> Hopefully there will be one good solution for this, for tools like
>> Cursive to do static analysis on (as it does with the Schema syntax). Not
>> sure if anyone is working on the spec-tools issue right now, looking
>> forward to the Orchestra implementation.
>>
>> Meanwhile: https://www.typescriptlang.org/docs/handbook/typescript-in-
>> 5-minutes.html
>>
>> lauantai 23. syyskuuta 2017 21.42.13 UTC+3 Jeaye kirjoitti:
>>>
>>> Last I checked, on our Clojure back-end, instrumentation was taking up
>>> 2% of our total test running time. This is with jdbc's instrumentation
>>> disabled though; I think it's significantly slower due to its extensive
>>> usage of s/or s/alt and spec regexes. Our specs are almost entirely s/keys
>>> and clojure.core predicates.
>>>
>>> Our fn spec coverage is 47% on the back-end. So the performance impact
>>> of instrumentation really hasn't been a concern.
>>>
>>> On Fri, Sep 22, 2017 at 10:18:52PM -0700, Didier wrote:
>>> > > The goal is to add the macro to orchestra, as a tool to help
>>> encourage spec'ing all functions.
>>> >
>>> > That would be great. My macro for now was also not supporting all defn
>>> cases yet. And it automatically instruments the fn with orchestra. So if
>>> orchestra had a more complete one defacto, I wouldn't need one.
>>> >
>>> > For performance, I've been thinking that caching validation (with some
>>> configurable cache bounds), or having sample based validation, so
>>> validating only a percentage of calls, and maybe even having the sampling
>>> rate controlled by execution time metrics, or cpu metrics or call rates,
>>> etc. would be interesting possibilities. So in prod, you could tweek the
>>> validation to only get as much of it as you can afford.
>>> >
>>> > --
>>> > You received this message because you are subscribed to the Google
>>> > Groups "Clojure" group.
>>> > To post to this group, send email to clo...@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+u...@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+u...@googlegroups.com.
>>> > For more options, visit https://groups.google.com/d/optout.
>>>
>>> --
> 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