Re: Kwargs vs explicit parameter map for APIs?

[Colin Fleming]

Thanks everyone - I was leaning towards maps and sounds like that's the
preferred approach.


On 26 April 2014 10:59, Gary Trakhman  wrote:

> If it's more than a few parameters, I prefer maps..  It enables the
> possibility of things like merge.
>
>
> On Fri, Apr 25, 2014 at 6:56 PM, Andrey Antukh  wrote:
>
>> Hi!
>>
>> I have the same doubt!
>>
>> However, At this time, I prefer use a explicit map instead keywords,
>> because for me is much clear that using keywords.
>>
>> Andrey.
>>
>>
>> 2014-04-26 0:41 GMT+02:00 Colin Fleming :
>>
>> Hi all,
>>>
>>> I'm working on an API at the moment, and I'm balancing whether to use
>>> inline keyword args which I would destructure in the functions, or whether
>>> to just pass an explicit params map as the last parameter. Comparison of
>>> the two options in case I'm not explaining myself well:
>>>
>>> Kwargs:
>>> (class/create-class :instancelist
>>> :description "My description"
>>> :implements  (keys class-methods)
>>> :methods (calculate-my-methods))
>>>
>>> Map:
>>> (class/create-class {:instancelist
>>>  :description "My description"
>>>  :implements  (keys class-methods)
>>>  :methods (calculate-my-methods)})
>>>
>>> A lot of APIs I've seen have favoured kwargs, and it undeniably makes
>>> for some pretty code - Seesaw is the best example I've seen here, the API
>>> is a thing of beauty. However it seems to me to have some issues:
>>>
>>>1. If I want to delegate to another call from within an API function
>>>and use the same arguments, it's really awkward: (apply delegate
>>>(mapcat identity args)) or some similarly awful black juxt magic. Or
>>>of course writing out all the parameters again, but that's even worse.
>>>2. It's more difficult to make parameters optional based on some
>>>runtime criteria since the params are baked into the function call. I 
>>> guess
>>>this is usually dealt with by making the calls handle nil for a 
>>> particular
>>>parameter.
>>>
>>> Both of these are much easier when passing an explicit map. Any
>>> preferences here, from either writing or using APIs like this?
>>>
>>> Cheers,
>>>
>>> Colin
>>>
>>> --
>>> 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.
>>>
>>
>>
>>
>> --
>> Andrey Antukh - Андрей Антух -  / <
>> n...@niwi.be>
>> http://www.niwi.be 
>> https://github.com/niwibe
>>
>> --
>> 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.
>

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

Re: Comprehensive lein template list?

[Mimmo Cosenza]

thanks!

On 26 Apr 2014, at 03:18, Colin Jones  wrote:

> Since these projects have to be named lein-template, you can actually get the 
> full list via `lein search`, provided you don't need to search 
> non-standard/private repositories.
> 
> I bumped my :user profile's :search-page-size to 1000, and got this when I 
> ran `lein-template`: https://gist.github.com/trptcolin/11309006
> 
> These could be cleaned up a bit to make it easier to review them (e.g. unique 
> by version; links to repos where applicable), but this should be a good 
> starting point.
> 
> 
> On Friday, April 25, 2014 5:49:47 PM UTC-5, puzzler wrote:
> Is there a list somewhere of the various lein templates?
> 
> I'm especially interested in comparing the templates for clojure web 
> development and/or clojurescript.  
> 
> The few I've sampled exhibit a wide variety of philosophies in terms of 
> whether to be minimalist or batteries-included (and which batteries are 
> included).  So a summary would be extremely useful.
> 
> Thanks,
> 
> Mark
> 
> -- 
> 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.



signature.asc
Description: Message signed with OpenPGP using GPGMail

Re: Kwargs vs explicit parameter map for APIs?

[Glen Mailer]

While reading the clojure.java.jdbc code yesterday, I discovered to my 
surprise that map destructuring can be used after an & in an arglist.

This should give you all the described benefits of the two approaches you 
mention

((fn [a & {:as d}] d) 1 :opt1 'blah :opt2 false)

You can also do defaults using :or - although these defaults don't get 
merged into the value of :as - so an explicit (merge) might be better.

((fn [a & {:keys [misc] :or {misc :misc-default} :as d}] [d misc]) 1 :opt1 
'blah :opt2 false)

Hope that makes sense!

Glen

On Friday, 25 April 2014 23:41:22 UTC+1, Colin Fleming wrote:
>
> Hi all,
>
> I'm working on an API at the moment, and I'm balancing whether to use 
> inline keyword args which I would destructure in the functions, or whether 
> to just pass an explicit params map as the last parameter. Comparison of 
> the two options in case I'm not explaining myself well:
>
> Kwargs:
> (class/create-class :instancelist
> :description "My description"
> :implements  (keys class-methods)
> :methods (calculate-my-methods))
>
> Map:
> (class/create-class {:instancelist
>  :description "My description"
>  :implements  (keys class-methods)
>  :methods (calculate-my-methods)})
>
> A lot of APIs I've seen have favoured kwargs, and it undeniably makes for 
> some pretty code - Seesaw is the best example I've seen here, the API is a 
> thing of beauty. However it seems to me to have some issues:
>
>1. If I want to delegate to another call from within an API function 
>and use the same arguments, it's really awkward: (apply delegate 
>(mapcat identity args)) or some similarly awful black juxt magic. Or 
>of course writing out all the parameters again, but that's even worse.
>2. It's more difficult to make parameters optional based on some 
>runtime criteria since the params are baked into the function call. I 
> guess 
>this is usually dealt with by making the calls handle nil for a particular 
>parameter. 
>
> Both of these are much easier when passing an explicit map. Any 
> preferences here, from either writing or using APIs like this?
>
> Cheers, 
>
> Colin
>

-- 
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: Example of using ANTLR from Clojure?

[Kranthi Rajoli]

Hi Paul,
  Do you mind outlining the method you used? I am exactly looking for the 
same. My Java skills are pathetic too.

Thanks,
Kras

On Wednesday, September 9, 2009 4:17:07 AM UTC+5:30, Paul Henning wrote:
>
> Thanks for the information.  Once I bit the bullet and learned a bit 
> of Java, it was actually pretty easy to call ANTLR from clojure, after 
> getting all the package naming figured out. 
>
> Paul 
>
> On Sep 6, 6:22 am, Laurent PETIT  wrote: 
> > 2009/9/5 Mike Hinchey  
> > 
> > > I don't know anything about it, but counterclockwise uses antlr. 
> > 
> > >http://groups.google.com/group/clojuredev-devel/browse_thread/thread/... 
>
> > 
> > That's true. To be more precise, we have a clojure lexer which is 
> > extensively used in Counterclockwise clojure source editor for syntax 
> > coloration. There is also the lexer part but it was developed a long 
> time 
> > ago (so may not be still accurate), and is not used yet (so maybe the 
> way 
> > the AST is constructed is nood in the good shape for most purpose). 
> > 
> > But to come back to your concern of using antlr from clojure : no, 
> > Counterclockwise is not yet written in clojure (just the client/server 
> part 
> > for communicating with running projects instances) and so you wil not be 
> > able to find examples for that, sorry :-( 
> > 
> > -- 
> > Laurent

-- 
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: Kwargs vs explicit parameter map for APIs?

[Colin Fleming]

Yes, that's the preferred way of accepting kwargs now, I think. But it's
just prettier syntax around the same problem. Note that using this form
doesn't accept an explicit map, I still have to place the params inline in
the function invocation. If I have:

(defn test1 [& {:keys [param1 param2] :as args}]
  ...)

(defn test2 [& {:keys [param1 param2] :as args}]
  ...)

Then when I call, say, test1, I still do it like this:

(test1 :param1 "some value" :param2 "some value")

Which means that if I want to have param2 be optional based on some runtime
value, there's really no other way to do it than:

(if condition?
  (test1 :param1 "..." :param2 "...")
  (test1 :param1 "..."))

With two parameters that might be ok, but with 10 it's basically
impossible, and your only option is to pass nil for some parameters and
handle that inside your function. And if I want to call test1 from test2 I
have to do either:

(defn test2 [& {:keys [param1 param2] :as args}]
  (test1 :param1 param1 :param2 param2))

or:

(defn test2 [& {:keys [param1 param2] :as args}]
  (apply test1 (mapcat identity args)))

The first again doesn't scale past 2 or 3 params, and doesn't allow you to
deal with optional parameters. The second probably needs a bit of head
scratching to figure out what it's even doing the first time you see it.

Note that if I pass an explicit map, I can still use the destructuring
forms above, just without the & symbol, and then I can just pass the args
map around, merge it for default parameters, add/remove params etc, and
everything is good.

Cheers,
Colin


On 26 April 2014 22:03, Glen Mailer  wrote:

> While reading the clojure.java.jdbc code yesterday, I discovered to my
> surprise that map destructuring can be used after an & in an arglist.
>
> This should give you all the described benefits of the two approaches you
> mention
>
> ((fn [a & {:as d}] d) 1 :opt1 'blah :opt2 false)
>
> You can also do defaults using :or - although these defaults don't get
> merged into the value of :as - so an explicit (merge) might be better.
>
> ((fn [a & {:keys [misc] :or {misc :misc-default} :as d}] [d misc]) 1 :opt1
> 'blah :opt2 false)
>
> Hope that makes sense!
>
> Glen
>
>
> On Friday, 25 April 2014 23:41:22 UTC+1, Colin Fleming wrote:
>>
>> Hi all,
>>
>> I'm working on an API at the moment, and I'm balancing whether to use
>> inline keyword args which I would destructure in the functions, or whether
>> to just pass an explicit params map as the last parameter. Comparison of
>> the two options in case I'm not explaining myself well:
>>
>> Kwargs:
>> (class/create-class :instancelist
>> :description "My description"
>> :implements  (keys class-methods)
>> :methods (calculate-my-methods))
>>
>> Map:
>> (class/create-class {:instancelist
>>  :description "My description"
>>  :implements  (keys class-methods)
>>  :methods (calculate-my-methods)})
>>
>> A lot of APIs I've seen have favoured kwargs, and it undeniably makes for
>> some pretty code - Seesaw is the best example I've seen here, the API is a
>> thing of beauty. However it seems to me to have some issues:
>>
>>1. If I want to delegate to another call from within an API function
>>and use the same arguments, it's really awkward: (apply delegate
>>(mapcat identity args)) or some similarly awful black juxt magic. Or
>>of course writing out all the parameters again, but that's even worse.
>>2. It's more difficult to make parameters optional based on some
>>runtime criteria since the params are baked into the function call. I 
>> guess
>>this is usually dealt with by making the calls handle nil for a particular
>>parameter.
>>
>> Both of these are much easier when passing an explicit map. Any
>> preferences here, from either writing or using APIs like this?
>>
>> Cheers,
>>
>> Colin
>>
>  --
> 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...@google

Re: Improving pprint behavior for anonymous functions

[Greg D]

Simpler yet using metadata:
(ns example.ppfn)

(defn print-pf [pf]
  (if-let [ppf (::ppf (meta pf))] ppf pf))

(defmacro partial* [& args]
  `(let [m#  (pr-str '(partial* ~@args))
 pf# (with-meta (partial ~@args) {::ppf m#})]
 (defmethod print-method (class pf#) [o# w#] (print-simple 
(example.ppfn/print-pf o#) w#))
 pf#))

In use:
user=> (def p1 (partial* + 1))
#'user/p1
user=> (p1 5)
6
user=> p1
(example.ppfn/partial* + 1)
user=> (def comma-join (partial* clojure.string/join ", "))
#'user/comma-join
user=> (comma-join ['a 'b 'c])
"a, b, c"
user=> comma-join
(example.ppfn/partial* clojure.string/join ", ")

-- 
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: Example of using ANTLR from Clojure?

[Armando Blancas]

I haven't touched this project in a while, but it might be useful.
https://github.com/blancas/tinypost
This file has the relevant interop code:
src/main/clojure/blancas/tinypost/scan.clj

On Saturday, April 26, 2014 3:04:50 AM UTC-7, Kranthi Rajoli wrote:

> Hi Paul,
>   Do you mind outlining the method you used? I am exactly looking for the 
> same. My Java skills are pathetic too.
>
> Thanks,
> Kras
>
> On Wednesday, September 9, 2009 4:17:07 AM UTC+5:30, Paul Henning wrote:
>>
>> Thanks for the information.  Once I bit the bullet and learned a bit 
>> of Java, it was actually pretty easy to call ANTLR from clojure, after 
>> getting all the package naming figured out. 
>>
>> Paul 
>>
>> On Sep 6, 6:22 am, Laurent PETIT  wrote: 
>> > 2009/9/5 Mike Hinchey  
>> > 
>> > > I don't know anything about it, but counterclockwise uses antlr. 
>> > 
>> > >http://groups.google.com/group/clojuredev-devel/browse_thread/thread/... 
>>
>> > 
>> > That's true. To be more precise, we have a clojure lexer which is 
>> > extensively used in Counterclockwise clojure source editor for syntax 
>> > coloration. There is also the lexer part but it was developed a long 
>> time 
>> > ago (so may not be still accurate), and is not used yet (so maybe the 
>> way 
>> > the AST is constructed is nood in the good shape for most purpose). 
>> > 
>> > But to come back to your concern of using antlr from clojure : no, 
>> > Counterclockwise is not yet written in clojure (just the client/server 
>> part 
>> > for communicating with running projects instances) and so you wil not 
>> be 
>> > able to find examples for that, sorry :-( 
>> > 
>> > -- 
>> > Laurent
>
>

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

ANN Major breaking public API changes coming to several ClojureWerkz projects

[Michael Klishin]

If you use a ClojureWerkz project or two please read this announcement:

http://blog.clojurewerkz.org/blog/2014/04/26/major-breaking-public-api-changes-coming-in-our-projects/
-- 
MK

http://github.com/michaelklishin
http://twitter.com/michaelklishin

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

ANN Neocons 3.0.0-rc1 is released

[Michael Klishin]

Neocons [1] is an idiomatic Clojure client for the Neo4J REST API.

3.0 has a *major breaking API change*.

Release notes:
http://blog.clojurewerkz.org/blog/2014/04/26/neocons-3-dot-0-0-rc1-is-released/

Background:
http://blog.clojurewerkz.org/blog/2014/04/26/major-breaking-public-api-changes-coming-in-our-projects/

1. http://clojureneo4j.info
-- 
MK

http://github.com/michaelklishin
http://twitter.com/michaelklishin

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

ANN Elastisch 2.0.0-rc1 is released

[Michael Klishin]

Elastisch [1] is a small, feature complete Clojure client for ElasticSearch
that supports both REST and native transports.

2.0 has one major breaking API change and is packed with improvements
related to ElasticSearch 1.0 and 1.1 releases.

Release notes:
http://blog.clojurewerkz.org/blog/2014/04/26/elastisch-2-dot-0-0-rc1-is-released/

Background:
http://blog.clojurewerkz.org/blog/2014/04/26/major-breaking-public-api-changes-coming-in-our-projects/

1. http://clojureelasticsearch.info
-- 
MK

http://github.com/michaelklishin
http://twitter.com/michaelklishin

-- 
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.memoize dependency problem

[Daniel Slutsky]

added an issue at
http://dev.clojure.org/jira/browse/CMEMOIZE-14


On Thursday, April 24, 2014 6:42:08 PM UTC+3, Daniel Slutsky wrote:
>
>
> Dear Clojure group,
> I am running into an interesting issue with clojure.core.memoize.
>
> I created a simple project depending on clojure.core.memoize.
> (defproject test-memoize "0.1.0-SNAPSHOT"
>   :description "FIXME: write description"
>   :url "http://example.com/FIXME";
>   :license {:name "Eclipse Public License"
> :url "http://www.eclipse.org/legal/epl-v10.html"}
>   :dependencies [[org.clojure/clojure "1.5.1"]
>  [org.clojure/core.memoize "0.5.6"]])
>
> Trying to use it, I run into the following problem:
>
> $ lein repl
> nREPL server started on port 38522 on host 127.0.0.1
> ...
> user=> (require 'clojure.core.memoize)
>
> user=> CompilerException java.lang.RuntimeException: No such var: 
> clojure.core.cache/through, compiling:(clojure/core/memoize.clj:52:3) 
>
> This pboblem has been recorded before:
>
> https://groups.google.com/forum/#!msg/light-table-discussion/f4kpZLFGBV8/oyFPaJ4yvwwJ
> http://www.raynes.me/logs/irc.freenode.net/clojure/2013-09-11.txt
> https://github.com/LightTable/LightTable/issues/794
>
> The suggested solution from the LightTable bug discussion 
> [[org.clojure/core.cache "0.6.3"]
>  [org.clojure/core.memoize "0.5.6" :exclusions [org.clojure/core.cache]]]
> does not seem to work.
>
> Any ideas?
>
>

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

Proposing a new Clojure documentation system (in Clojure)

[Val Waeselynck]

Hello to all,

*Short version :* I think Clojure needs a documentation system in Clojure, 
I would like to know if some efforts exist in that direction, and I am 
willing to create it / contribute to it.

*Long version :*

I've been thinking for a while that the Clojure community could benefit a 
lot from a more sophisticated and ergonomic documentation system. 

I have seen some existing plugins like lein-sphinx, but I think it would be 
really good to have documentation that would be written in Clojure, for the 
following reasons :

   - we're all very fond of Clojure data structures and their syntax. (I 
   don't know about you, but I find that even HTML looks better in 
Clojurethan in HTML). Plus, Clojure 
programmers already know how to edit them.
   - (better reason) The facts that Vars are first-class citizens and that 
   symbols can be referred explicitly with hardly any ceremony (macros) are a 
   exceptional opportunity to make smart and highly-structured documentation 
   very easily.
   - if it's in Clojure, Clojure programmers can seamlessly build *ad 
hoc*documentation functionality on top of it to suit their own particular needs.

I haven't found anything of the like yet, and if it exists, I would be 
grateful if someone would redirect me to it.

Here are *my thoughts on this :*

   1. Clojure doc-strings, although they are quite handy as reminders and 
   for doc-indexation, are *too raw a content*. Even when they are done 
   right, they tend to be cumbersome, and it's too bad to have such concise 
   code drown in the middle of so much documentation. What's more, I believe 
   that when programmers program a function (or anything), they tend to think 
   more about the implementation than the (uninformed) usage, so they have 
   little incentive to make it right.
   2. Building on 1. having a system where documentation and programs live 
   in separate files, in the same way as tests, would enforce a healthy 
   separation of concerns. Importantly, it would make life much easier on the 
   Version Control perspective.
   3. Documentation should probably be made differently than what people 
   have got accustomed to by classical languages. Because you seldom find 
   types, and because IMHO Clojure programs are formed more by factoring out 
   recurring mechanisms in code than from implementing intellectual 
   abstractions, the relevant concepts tend not to be obvious in the code. 
   Since in Clojure we program with verbs, not 
nouns,
 
   I think *documentation is best made by example*.
   4. Documentation of a Var should not be a formal description of what it 
   is and what it does with some cryptically-named variables. *Every bit of 
   documentation should be a micro-tutorial*. Emphasis should be put on 
   usage, examples, tips, pitfalls, howtos.
   5. There should be structure in the documentation, and it shouldn't be 
   just :see-also links - *there should be semantics* in it.  For example, 
   some functions/macros are really meant to be nothing but shorthands for 
   calling other functions : that kind of relationship should be explicitly 
   documented.
   6. Documentation should not be just information about each separate Var 
   in a namespace. There should be a hierarchy to make the most useful 
   elements of an API more obvious. Also, adding cross-vars documentation 
   elements such as tags and topics could make it easier to navigate and 
   understand.
   7. *Documentation in the REPL is great*, it was one of the very good 
   surprises when I started learning Clojure. However, a rich and good-looking 
   presentation like in Javadocs would be welcome too.
   
Of course, all of the above are just vague principles. Here is *some 
functionality I suggest for a start :*

   1. Documentation content elements could be written in a Clojure DSL 
   emulating some kind of docbook-like markup language.
   2. On the user side, the documentation would be accessible through a 
   generated web interface, a REPL interface, and maybe other formats like 
   Wiki.
   3. Documentation could be programmed anywhere in a project by simply 
   referring to the relevant Vars and calling the documentation API. Ideally, 
   there would be a dedicated folder for documentation files, and a Leiningen 
   plugin to compile them and generate the HTML from them.
   4. I often find myself lost because I have no idea what shape some 
   arguments to a function should have, such as config maps and maps 
   representing application-specific models. To adress this, I propose to 
   explicitly declare and describe *"stereotypes"* in the documentation. 
   Such stereotypes could be, for instance, "JDBC connection" or "Ring 
   middleware". From what I have seen, some good 
workhas already been done in that 
direction, but it would be good to make room 
  

Re: Comprehensive lein template list?

[Mimmo Cosenza]

Regarding the lein-templates for cljs going from very minimal to batteries 
included, my personal opinion is that we should be able to create something like

http://yeoman.io/index.html

Any thoughts?

Thanks

mimmo

On 26 Apr 2014, at 00:49, Mark Engelberg  wrote:

> Is there a list somewhere of the various lein templates?
> 
> I'm especially interested in comparing the templates for clojure web 
> development and/or clojurescript.  
> 
> The few I've sampled exhibit a wide variety of philosophies in terms of 
> whether to be minimalist or batteries-included (and which batteries are 
> included).  So a summary would be extremely useful.
> 
> Thanks,
> 
> Mark
> 
> -- 
> 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.



signature.asc
Description: Message signed with OpenPGP using GPGMail

Re: Improving pprint behavior for anonymous functions

[Matthew DeVore]

Greg's is a nice and clean solution for the data visualization problem, 
assuming you're only going to use partials.

I hacked together a solution to support functions with equality semantics, 
if anyone is interested. It doesn't support anonymous functions or 
closures, but doing that would require some advanced macro magic and I 
don't want to invest the time in that now. Below is an example of usage - 
the source is on my 
Github
.

(defnv adder [value] [another-num]
  (+ value another-num))

(defnv exclaimer [bangs mark] [phrase]
  (apply str phrase (repeat bangs mark)))

(def adder-4 (adder 4))
(def adder-0 (adder 0))
(def exclaimer-?? (exclaimer 2 "?"))

(deftest test-defnv-equality
  (is (= (adder 1) (adder 1)))
  (is (not= (exclaimer 2 "!") exclaimer-??)))

(deftest test-defnv-invocation
  (is (= 4 (adder-4 0)))
  (is (= 44 (adder-0 44)))
  (is (= 55 (adder-4 51)))
  (is (= "Hello??" (exclaimer-?? "Hello"

(deftest test-defnv-print-method
  (are [expected vfn]
   (let [w (new java.io.StringWriter)]
 (print-method vfn w)
 (= expected (str w)))
   "(adder 0)" adder-0
   "(adder 4)" adder-4
   "(exclaimer 2 \"?\")" exclaimer-??))


在 2014年4月26日星期六UTC-7上午5时27分37秒，Greg D写道：
>
> Simpler yet using metadata:
> (ns example.ppfn)
>
> (defn print-pf [pf]
>   (if-let [ppf (::ppf (meta pf))] ppf pf))
>
> (defmacro partial* [& args]
>   `(let [m#  (pr-str '(partial* ~@args))
>  pf# (with-meta (partial ~@args) {::ppf m#})]
>  (defmethod print-method (class pf#) [o# w#] (print-simple 
> (example.ppfn/print-pf o#) w#))
>  pf#))
>
> In use:
> user=> (def p1 (partial* + 1))
> #'user/p1
> user=> (p1 5)
> 6
> user=> p1
> (example.ppfn/partial* + 1)
> user=> (def comma-join (partial* clojure.string/join ", "))
> #'user/comma-join
> user=> (comma-join ['a 'b 'c])
> "a, b, c"
> user=> comma-join
> (example.ppfn/partial* clojure.string/join ", ")
>

-- 
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: Proposing a new Clojure documentation system (in Clojure)

[Gary Trakhman]

This is a lovely idea.

I think prismatic schema is one well-accepted way to document data shapes,
but it's expected to be used inline. It would be nice to have flexibility
in what description systems are used in addition to flexibility of where
the docs live.

I agree that being able to see and reason about bare code with no hassle is
a (personal) demotivator for documentation, but where the docs live should
be up to the implementor.  Having a code-based system means we can use and
improve existing runtime tooling to navigate and interact with it.  This
would make a great cider middleware :-).

On Saturday, April 26, 2014, Val Waeselynck  wrote:

> Hello to all,
>
> *Short version :* I think Clojure needs a documentation system in
> Clojure, I would like to know if some efforts exist in that direction, and
> I am willing to create it / contribute to it.
>
> *Long version :*
>
> I've been thinking for a while that the Clojure community could benefit a
> lot from a more sophisticated and ergonomic documentation system.
>
> I have seen some existing plugins like lein-sphinx, but I think it would
> be really good to have documentation that would be written in Clojure, for
> the following reasons :
>
>- we're all very fond of Clojure data structures and their syntax. (I
>don't know about you, but I find that even HTML looks better in 
> Clojurethan in HTML). Plus, Clojure 
> programmers already know how to edit them.
>- (better reason) The facts that Vars are first-class citizens and
>that symbols can be referred explicitly with hardly any ceremony (macros)
>are a exceptional opportunity to make smart and highly-structured
>documentation very easily.
>- if it's in Clojure, Clojure programmers can seamlessly build *ad 
> hoc*documentation functionality on top of it to suit their own particular 
> needs.
>
> I haven't found anything of the like yet, and if it exists, I would be
> grateful if someone would redirect me to it.
>
> Here are *my thoughts on this :*
>
>1. Clojure doc-strings, although they are quite handy as reminders and
>for doc-indexation, are *too raw a content*. Even when they are done
>right, they tend to be cumbersome, and it's too bad to have such concise
>code drown in the middle of so much documentation. What's more, I believe
>that when programmers program a function (or anything), they tend to think
>more about the implementation than the (uninformed) usage, so they have
>little incentive to make it right.
>2. Building on 1. having a system where documentation and programs
>live in separate files, in the same way as tests, would enforce a healthy
>separation of concerns. Importantly, it would make life much easier on the
>Version Control perspective.
>3. Documentation should probably be made differently than what people
>have got accustomed to by classical languages. Because you seldom find
>types, and because IMHO Clojure programs are formed more by factoring out
>recurring mechanisms in code than from implementing intellectual
>abstractions, the relevant concepts tend not to be obvious in the code.
>Since in Clojure we program with verbs, not 
> nouns,
>I think *documentation is best made by example*.
>4. Documentation of a Var should not be a formal description of what
>it is and what it does with some cryptically-named variables. *Every
>bit of documentation should be a micro-tutorial*. Emphasis should be
>put on usage, examples, tips, pitfalls, howtos.
>5. There should be structure in the documentation, and it shouldn't be
>just :see-also links - *there should be semantics* in it.  For
>example, some functions/macros are really meant to be nothing but
>shorthands for calling other functions : that kind of relationship should
>be explicitly documented.
>6. Documentation should not be just information about each separate
>Var in a namespace. There should be a hierarchy to make the most useful
>elements of an API more obvious. Also, adding cross-vars documentation
>elements such as tags and topics could make it easier to navigate and
>understand.
>7. *Documentation in the REPL is great*, it was one of the very good
>surprises when I started learning Clojure. However, a rich and good-looking
>presentation like in Javadocs would be welcome too.
>
> Of course, all of the above are just vague principles. Here is *some
> functionality I suggest for a start :*
>
>1. Documentation content elements could be written in a Clojure DSL
>emulating some kind of docbook-like markup language.
>2. On the user side, the documentation would be accessible through a
>generated web interface, a REPL interface, and maybe other formats like
>Wiki.
>3. Documentation could be programmed anywhere in a project by s

Re: Proposing a new Clojure documentation system (in Clojure)

[Jason Felice]

Personally, I like documentation in the same place as the code it
documents And I'd love to have the  tests in the same file as well.

In both cases, I think the things are highly coupled by their nature, and
therefore I want them together (OK, tests aren't always - in the cases they
aren't, put them in a separate file).  I've reminded people that the SRP
("any piece of code should have one reason to change") implies the
converse, which I phrase as "Code which changes together, stays together."

That said, I like the idea of more structured documentation.  (Possibly
including test cases!  Python has test runners which verify examples in doc
strings, for example.)
On Apr 26, 2014 4:31 PM, "Gary Trakhman"  wrote:

> This is a lovely idea.
>
> I think prismatic schema is one well-accepted way to document data shapes,
> but it's expected to be used inline. It would be nice to have flexibility
> in what description systems are used in addition to flexibility of where
> the docs live.
>
> I agree that being able to see and reason about bare code with no hassle
> is a (personal) demotivator for documentation, but where the docs live
> should be up to the implementor.  Having a code-based system means we can
> use and improve existing runtime tooling to navigate and interact with it.
>  This would make a great cider middleware :-).
>
> On Saturday, April 26, 2014, Val Waeselynck  wrote:
>
>> Hello to all,
>>
>> *Short version :* I think Clojure needs a documentation system in
>> Clojure, I would like to know if some efforts exist in that direction, and
>> I am willing to create it / contribute to it.
>>
>> *Long version :*
>>
>> I've been thinking for a while that the Clojure community could benefit a
>> lot from a more sophisticated and ergonomic documentation system.
>>
>> I have seen some existing plugins like lein-sphinx, but I think it would
>> be really good to have documentation that would be written in Clojure, for
>> the following reasons :
>>
>>- we're all very fond of Clojure data structures and their syntax. (I
>>don't know about you, but I find that even HTML looks better in
>>Clojure  than in HTML). Plus,
>>Clojure programmers already know how to edit them.
>>- (better reason) The facts that Vars are first-class citizens and
>>that symbols can be referred explicitly with hardly any ceremony (macros)
>>are a exceptional opportunity to make smart and highly-structured
>>documentation very easily.
>>- if it's in Clojure, Clojure programmers can seamlessly build *ad
>>hoc* documentation functionality on top of it to suit their own
>>particular needs.
>>
>> I haven't found anything of the like yet, and if it exists, I would be
>> grateful if someone would redirect me to it.
>>
>> Here are *my thoughts on this :*
>>
>>1. Clojure doc-strings, although they are quite handy as reminders
>>and for doc-indexation, are *too raw a content*. Even when they are
>>done right, they tend to be cumbersome, and it's too bad to have such
>>concise code drown in the middle of so much documentation. What's more, I
>>believe that when programmers program a function (or anything), they tend
>>to think more about the implementation than the (uninformed) usage, so 
>> they
>>have little incentive to make it right.
>>2. Building on 1. having a system where documentation and programs
>>live in separate files, in the same way as tests, would enforce a healthy
>>separation of concerns. Importantly, it would make life much easier on the
>>Version Control perspective.
>>3. Documentation should probably be made differently than what people
>>have got accustomed to by classical languages. Because you seldom find
>>types, and because IMHO Clojure programs are formed more by factoring out
>>recurring mechanisms in code than from implementing intellectual
>>abstractions, the relevant concepts tend not to be obvious in the code.
>>Since in Clojure we program with verbs, not 
>> nouns,
>>I think *documentation is best made by example*.
>>4. Documentation of a Var should not be a formal description of what
>>it is and what it does with some cryptically-named variables. *Every
>>bit of documentation should be a micro-tutorial*. Emphasis should be
>>put on usage, examples, tips, pitfalls, howtos.
>>5. There should be structure in the documentation, and it shouldn't
>>be just :see-also links - *there should be semantics* in it.  For
>>example, some functions/macros are really meant to be nothing but
>>shorthands for calling other functions : that kind of relationship should
>>be explicitly documented.
>>6. Documentation should not be just information about each separate
>>Var in a namespace. There should be a hierarchy to make the most useful
>>elements of an API mor

Re: Proposing a new Clojure documentation system (in Clojure)

[Val Waeselynck]

Fair points. Well, leaving the possibility to document the code from just 
anywhere is what I had in mind.

Le samedi 26 avril 2014 22:52:41 UTC+2, Jason Felice a écrit :
>
> Personally, I like documentation in the same place as the code it 
> documents And I'd love to have the  tests in the same file as well.
>
> In both cases, I think the things are highly coupled by their nature, and 
> therefore I want them together (OK, tests aren't always - in the cases they 
> aren't, put them in a separate file).  I've reminded people that the SRP 
> ("any piece of code should have one reason to change") implies the 
> converse, which I phrase as "Code which changes together, stays together."
>
> That said, I like the idea of more structured documentation.  (Possibly 
> including test cases!  Python has test runners which verify examples in doc 
> strings, for example.)
> On Apr 26, 2014 4:31 PM, "Gary Trakhman" > 
> wrote:
>
>> This is a lovely idea. 
>>
>> I think prismatic schema is one well-accepted way to document data 
>> shapes, but it's expected to be used inline. It would be nice to have 
>> flexibility in what description systems are used in addition to flexibility 
>> of where the docs live. 
>>
>> I agree that being able to see and reason about bare code with no hassle 
>> is a (personal) demotivator for documentation, but where the docs live 
>> should be up to the implementor.  Having a code-based system means we can 
>> use and improve existing runtime tooling to navigate and interact with it. 
>>  This would make a great cider middleware :-).
>>
>> On Saturday, April 26, 2014, Val Waeselynck 
>> > 
>> wrote:
>>
>>> Hello to all,
>>>
>>> *Short version :* I think Clojure needs a documentation system in 
>>> Clojure, I would like to know if some efforts exist in that direction, and 
>>> I am willing to create it / contribute to it.
>>>
>>> *Long version :*
>>>
>>> I've been thinking for a while that the Clojure community could benefit 
>>> a lot from a more sophisticated and ergonomic documentation system. 
>>>
>>> I have seen some existing plugins like lein-sphinx, but I think it would 
>>> be really good to have documentation that would be written in Clojure, for 
>>> the following reasons :
>>>
>>>- we're all very fond of Clojure data structures and their syntax. 
>>>(I don't know about you, but I find that even HTML looks better in 
>>>Clojure  than in HTML). Plus, 
>>>Clojure programmers already know how to edit them.
>>>- (better reason) The facts that Vars are first-class citizens and 
>>>that symbols can be referred explicitly with hardly any ceremony 
>>> (macros) 
>>>are a exceptional opportunity to make smart and highly-structured 
>>>documentation very easily. 
>>>- if it's in Clojure, Clojure programmers can seamlessly build *ad 
>>>hoc* documentation functionality on top of it to suit their own 
>>>particular needs.
>>>
>>> I haven't found anything of the like yet, and if it exists, I would be 
>>> grateful if someone would redirect me to it.
>>>
>>> Here are *my thoughts on this :*
>>>
>>>1. Clojure doc-strings, although they are quite handy as reminders 
>>>and for doc-indexation, are *too raw a content*. Even when they are 
>>>done right, they tend to be cumbersome, and it's too bad to have such 
>>>concise code drown in the middle of so much documentation. What's more, 
>>> I 
>>>believe that when programmers program a function (or anything), they 
>>> tend 
>>>to think more about the implementation than the (uninformed) usage, so 
>>> they 
>>>have little incentive to make it right.
>>>2. Building on 1. having a system where documentation and programs 
>>>live in separate files, in the same way as tests, would enforce a 
>>> healthy 
>>>separation of concerns. Importantly, it would make life much easier on 
>>> the 
>>>Version Control perspective. 
>>>3. Documentation should probably be made differently than what 
>>>people have got accustomed to by classical languages. Because you seldom 
>>>find types, and because IMHO Clojure programs are formed more by 
>>> factoring 
>>>out recurring mechanisms in code than from implementing intellectual 
>>>abstractions, the relevant concepts tend not to be obvious in the code. 
>>>Since in Clojure we program with verbs, not 
>>> nouns,
>>>  
>>>I think *documentation is best made by example*.
>>>4. Documentation of a Var should not be a formal description of what 
>>>it is and what it does with some cryptically-named variables. *Every 
>>>bit of documentation should be a micro-tutorial*. Emphasis should be 
>>>put on usage, examples, tips, pitfalls, howtos. 
>>>5. There should be structure in the documentation, and it shouldn't 
>>>be just :see-also links - *there should be semantics* in i

Re: Problem in loop (for loop) with Cascalog results

[sindhu hosamane]

>
> Thanks a lot . i got it wrong in my cascalog query. Now it worked.
>

-- 
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: [ClojureScript] ANN: Om 0.6.1, moving towards independently addressable components

[Moritz Ulrich]

Could it be that 0.6.1 doesn't trigger a re-render of a component when
just `:opts' has changed? I have a parent component with passes a
boolean (`:selected?') down to it's children in the `:opts'-map.
The parent-component's `render' is called, but the children's isn't anymore.

I understand that this might be the expected (and even sensible)
behavior. Still, it's a difference and it might be worth mentioning.

(Btw. I see some *massive* improvements in eliminating non-changed
branches, it's awesome)

On Thu, Apr 24, 2014 at 7:03 PM, David Nolen  wrote:
> Om 0.6.1 significantly changes how component local state works - we now rely
> on React's forceUpdate to update components that use local state. This is a
> significant change so I would like people test this out on their existing
> code bases as soon as possible.
>
> The immediate benefit is that components now use `=` for the
> shouldComponentUpdate logic instead of `identical?`. This means considerably
> more flexibility with regards to what a component may receive without taking
> a performance hit with respect to rendering. Even more importantly it's a
> big step towards independently addressable components.
>
> What are independently addressable components? Currently many people
> struggle with the fact that parent components must take all the data
> associated with their children. This often results in a tight coupling that
> is not ideal for real applications. The next few releases of Om will be
> focused on providing a sensible solution to this issue without backing away
> from the existing efficient time travel capabilities.
>
> Feedback welcome!
>
> http://github.com/swannodette/om
>
> David
>
> --
> Note that posts from new members are moderated - please be patient with your
> first post.
> ---
> You received this message because you are subscribed to the Google Groups
> "ClojureScript" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to clojurescript+unsubscr...@googlegroups.com.
> To post to this group, send email to clojurescr...@googlegroups.com.
> Visit this group at http://groups.google.com/group/clojurescript.

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

Unity 3d and Clojure

[Jacob Goodson]

Hey guys I have seen this... 
http://f.cl.ly/items/2T2d340o0k0W2d44212G/clj2.gif

Now, I want to know... has anything developed since?  Is it available to 
all?  

-- 
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: Proposing a new Clojure documentation system (in Clojure)

[Mars0i]

Some thoughts:

Having concise documentation in the same place as the code minimizes a 
certain kind of work:  I want my functions to be commented in the source 
file so that someone reading it later (maybe me) will quickly understand 
what they're supposed to do.  If Clojure didn't have docstrings, I'd put 
similar information, although maybe more terse, in comments.  As it is, I 
just write the docstring, and I've accomplished two things in one.  If all 
of the documentation was in another file, I'd have to do at least 1.5 times 
more work just to produce the kind of docstrings I produce now.

Some docstrings (e.g. for xy-plot in Incanter) are too long for convenient 
use at a repl.  So I appreciate the idea of providing different levels of 
documentation.  What's displayed by default at a prompt should be short.

I like the general idea of the Valentin's proposal, but I don't understand 
every bit of it.  It sounds complicated.  Personally, I'd rather see 
something that's relatively simple, and good enough, than something that's 
perfect but unwieldy.  If it's too difficult, people won't use it, or 
they'll waste time, or feel that the Clojure community expects them to 
spend too much time on something that detracts from what's important.  I am 
someone who I think has put more time into documentation more than most of 
the programmers I've worked with.  I'm in favor of encouraging more 
documentation of code.  But documentation tools should not make the process 
much harder than it is.  Ideally, they should make it easier, but some 
extra cost is worthwhile for extra payoff later.

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