ClojureDocs.org
75 views
Skip to first unread message
zkim
Jul 9, 2010, 4:32:05 AM7/9/10
to Clojure
Hi All,
I'll try to keep this short.
I've gotten a lot out of Clojure: I can honestly say that learning
this language, and being part of this community has made me a better,
happier developer, and I wanted to give something back.
One of the pain points that I encountered when learning the language
was a lack of examples specific to the individual functions I was
trying to wrap my head around at any given time. So I took a whack at
the problem, and came up with http://clojuredocs.org. It's a site
that (I'm hoping) will fill this need by providing a centralized
examples database, along with solid search capabilities across both
core and third party libraries (core being the focus).
Implementation:
ClojureDocs.org is a rails site backed by MySQL, along with some
clojure code to pull the namespaces / metadata / source and dump them
into the database.
Highlights:
1. Documentation and source for Clojure core, contrib, and a few third
party libraries (random selection out of what I'm personally familiar
with, and whatever was on the github trends page that day).
2. Search for a var across the whole ecosystem or in a specific
library.
3. Per var wiki-style examples section.
4. Per var comments section.
5. Per var vars-in-this-var and this-var-used-in section (my personal
favorite). Looking for a real-world example of a specific function?
This is for you. For example, http://clojuredocs.org/v/1978, just
below the source section.
Lowlights:
1. Ugly URLs! There's a problem in the way that URLs with encoded
question marks are being handled, so I had to move from
http://clojuredocs.org/clj-ssh/clj-ssh.core/file-path to
http://clojuredocs.org/v/1484. I've got an email out to the Phusion
Passenger mailing list (http://groups.google.com/group/phusion-
passenger/browse_thread/thread/ed2eadfdac5c166f) but if you've got any
experience in this area drop me a line.
2. Strange var names (http://clojuredocs.org/v/781). Probably a bug
in the import process.
3. General rough-around-the-edges-ness.
I'm treating this as an alpha, and I'd really like feedback as to:
a. How useful this would be to the community.
b. Specific likes / dislikes about this alpha release.
c. Feature requests.
I've set up a feedback mechanism directly through the site (User
Voice), which allows voting on specific posts. I'm also considering
setting up a google group for general discussion. Feel free to
contact me directly through email.
Questions / thoughts?
-Zack
I'll try to keep this short.
I've gotten a lot out of Clojure: I can honestly say that learning
this language, and being part of this community has made me a better,
happier developer, and I wanted to give something back.
One of the pain points that I encountered when learning the language
was a lack of examples specific to the individual functions I was
trying to wrap my head around at any given time. So I took a whack at
the problem, and came up with http://clojuredocs.org. It's a site
that (I'm hoping) will fill this need by providing a centralized
examples database, along with solid search capabilities across both
core and third party libraries (core being the focus).
Implementation:
ClojureDocs.org is a rails site backed by MySQL, along with some
clojure code to pull the namespaces / metadata / source and dump them
into the database.
Highlights:
1. Documentation and source for Clojure core, contrib, and a few third
party libraries (random selection out of what I'm personally familiar
with, and whatever was on the github trends page that day).
2. Search for a var across the whole ecosystem or in a specific
library.
3. Per var wiki-style examples section.
4. Per var comments section.
5. Per var vars-in-this-var and this-var-used-in section (my personal
favorite). Looking for a real-world example of a specific function?
This is for you. For example, http://clojuredocs.org/v/1978, just
below the source section.
Lowlights:
1. Ugly URLs! There's a problem in the way that URLs with encoded
question marks are being handled, so I had to move from
http://clojuredocs.org/clj-ssh/clj-ssh.core/file-path to
http://clojuredocs.org/v/1484. I've got an email out to the Phusion
Passenger mailing list (http://groups.google.com/group/phusion-
passenger/browse_thread/thread/ed2eadfdac5c166f) but if you've got any
experience in this area drop me a line.
2. Strange var names (http://clojuredocs.org/v/781). Probably a bug
in the import process.
3. General rough-around-the-edges-ness.
I'm treating this as an alpha, and I'd really like feedback as to:
a. How useful this would be to the community.
b. Specific likes / dislikes about this alpha release.
c. Feature requests.
I've set up a feedback mechanism directly through the site (User
Voice), which allows voting on specific posts. I'm also considering
setting up a google group for general discussion. Feel free to
contact me directly through email.
Questions / thoughts?
-Zack
Victor Olteanu
Jul 9, 2010, 11:16:09 AM7/9/10
to clo...@googlegroups.com
I took a first look and I have to say that the idea is genius and I love what you put up together this far.
It is difficult to keep up with what's happening in the Clojure world, and this kind of central place to keep track of things was needed. The examples are also a strong point.
I hope the site will grow with many people's contributions.
Victor
--
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
Lee Hinman
Jul 9, 2010, 12:08:35 PM7/9/10
to clo...@googlegroups.com
> Questions / thoughts?
>
> -Zack
>
> -Zack
Hi Zack,
First off, I think it looks great, and it definitely seems useful when
trying to find an example of a particular API call.
Few suggestions:
1. The headers for each section (Doc, Source, Example(s)) don't
differentiate themselves from the regular doc text enough, maybe
bold/underline/color them to make them show up more?
2. The links to the source code should link to
http://github.com/clojure/clojure, I believe the richhickey clojure
repo has been transitioned there.
3. I know non-confirmation logins are really nice, but should the site
attract any spammers, you may want to look at adding an email account
confirmation (since spammers could go nuts adding comments to pages).
Looks awesome, hope it gets some love from the Clojure community.
- Lee
David Nolen
Jul 9, 2010, 12:21:52 PM7/9/10
to clo...@googlegroups.com
On Fri, Jul 9, 2010 at 4:32 AM, zkim <zacha...@gmail.com> wrote:
Questions / thoughts?
-Zack
This is great. I think the main thing is not duplicating effort. This and clojure-examples.appspot.com should really join forces.
David
.Bill Smith
Jul 9, 2010, 12:30:56 PM7/9/10
to Clojure
Having contributed a lot of examples to clojure-examples.appspot.com
this week, I agree that it would be a shame to duplicate efforts.
On Jul 9, 11:21 am, David Nolen <dnolen.li...@gmail.com> wrote:
this week, I agree that it would be a shame to duplicate efforts.
On Jul 9, 11:21 am, David Nolen <dnolen.li...@gmail.com> wrote:
Dmitry Kakurin
Jul 9, 2010, 2:19:16 PM7/9/10
to Clojure
It's a great idea, and the site looks very good.
Two suggestions:
1. Move examples section above source code section
2. Add OpenID sign in support. Personally I'm instantly repelled by
sites asking me to create another account/password. And I'm sure I'm
not alone. Stackoverflow.com is a great example of how effortless it
could be to "register".
- Dmitry
On Jul 9, 1:32 am, zkim <zachary....@gmail.com> wrote:
> Hi All,
>
> I'll try to keep this short.
>
> I've gotten a lot out of Clojure: I can honestly say that learning
> this language, and being part of this community has made me a better,
> happier developer, and I wanted to give something back.
>
> One of the pain points that I encountered when learning the language
> was a lack of examples specific to the individual functions I was
> trying to wrap my head around at any given time. So I took a whack at
> the problem, and came up withhttp://clojuredocs.org. It's a site
Two suggestions:
1. Move examples section above source code section
2. Add OpenID sign in support. Personally I'm instantly repelled by
sites asking me to create another account/password. And I'm sure I'm
not alone. Stackoverflow.com is a great example of how effortless it
could be to "register".
- Dmitry
On Jul 9, 1:32 am, zkim <zachary....@gmail.com> wrote:
> Hi All,
>
> I'll try to keep this short.
>
> I've gotten a lot out of Clojure: I can honestly say that learning
> this language, and being part of this community has made me a better,
> happier developer, and I wanted to give something back.
>
> One of the pain points that I encountered when learning the language
> was a lack of examples specific to the individual functions I was
> trying to wrap my head around at any given time. So I took a whack at
> that (I'm hoping) will fill this need by providing a centralized
> examples database, along with solid search capabilities across both
> core and third party libraries (core being the focus).
>
> Implementation:
> ClojureDocs.org is a rails site backed by MySQL, along with some
> clojure code to pull the namespaces / metadata / source and dump them
> into the database.
>
> Highlights:
> 1. Documentation and source for Clojure core, contrib, and a few third
> party libraries (random selection out of what I'm personally familiar
> with, and whatever was on the github trends page that day).
>
> 2. Search for a var across the whole ecosystem or in a specific
> library.
>
> 3. Per var wiki-style examples section.
>
> 4. Per var comments section.
>
> 5. Per var vars-in-this-var and this-var-used-in section (my personal
> favorite). Looking for a real-world example of a specific function?
> This is for you. For example,http://clojuredocs.org/v/1978, just
> examples database, along with solid search capabilities across both
> core and third party libraries (core being the focus).
>
> Implementation:
> ClojureDocs.org is a rails site backed by MySQL, along with some
> clojure code to pull the namespaces / metadata / source and dump them
> into the database.
>
> Highlights:
> 1. Documentation and source for Clojure core, contrib, and a few third
> party libraries (random selection out of what I'm personally familiar
> with, and whatever was on the github trends page that day).
>
> 2. Search for a var across the whole ecosystem or in a specific
> library.
>
> 3. Per var wiki-style examples section.
>
> 4. Per var comments section.
>
> 5. Per var vars-in-this-var and this-var-used-in section (my personal
> favorite). Looking for a real-world example of a specific function?
> below the source section.
>
> Lowlights:
> 1. Ugly URLs! There's a problem in the way that URLs with encoded
> question marks are being handled, so I had to move fromhttp://clojuredocs.org/clj-ssh/clj-ssh.core/file-pathtohttp://clojuredocs.org/v/1484. I've got an email out to the Phusion
>
> Lowlights:
> 1. Ugly URLs! There's a problem in the way that URLs with encoded
Alex Miller
Jul 9, 2010, 2:25:14 PM7/9/10
to Clojure
I've actually been thinking about this exact same kind of site for a
while now and I'm thrilled that I was too lazy to do it so that you
could do it instead. :)
One idea that I have that I think would be killer would be to provide
an API to look up one your examples at the repl so I could do
something like:
=> (use 'clojuredocs)
=> (example map)
clojure.core/map (since 1.0)
(map inc [1 2 3 4 5])
(2 3 4 5 6)
There are of course many variants of some functions and different
forms of use, so dealing with the best way to provide useful help
without an overwhelming number of examples is tricky in the repl, but
I think worth doing. Along with doc and source, I think example would
be a killer addition to allowing you to explore the libraries from the
comfort of your repl.
Alex
On Jul 9, 3:32 am, zkim <zachary....@gmail.com> wrote:
> Hi All,
>
> I'll try to keep this short.
>
> I've gotten a lot out of Clojure: I can honestly say that learning
> this language, and being part of this community has made me a better,
> happier developer, and I wanted to give something back.
>
> One of the pain points that I encountered when learning the language
> was a lack of examples specific to the individual functions I was
> trying to wrap my head around at any given time. So I took a whack at
> the problem, and came up withhttp://clojuredocs.org. It's a site
while now and I'm thrilled that I was too lazy to do it so that you
could do it instead. :)
One idea that I have that I think would be killer would be to provide
an API to look up one your examples at the repl so I could do
something like:
=> (use 'clojuredocs)
=> (example map)
clojure.core/map (since 1.0)
(map inc [1 2 3 4 5])
(2 3 4 5 6)
There are of course many variants of some functions and different
forms of use, so dealing with the best way to provide useful help
without an overwhelming number of examples is tricky in the repl, but
I think worth doing. Along with doc and source, I think example would
be a killer addition to allowing you to explore the libraries from the
comfort of your repl.
Alex
On Jul 9, 3:32 am, zkim <zachary....@gmail.com> wrote:
> Hi All,
>
> I'll try to keep this short.
>
> I've gotten a lot out of Clojure: I can honestly say that learning
> this language, and being part of this community has made me a better,
> happier developer, and I wanted to give something back.
>
> One of the pain points that I encountered when learning the language
> was a lack of examples specific to the individual functions I was
> trying to wrap my head around at any given time. So I took a whack at
> that (I'm hoping) will fill this need by providing a centralized
> examples database, along with solid search capabilities across both
> core and third party libraries (core being the focus).
>
> Implementation:
> ClojureDocs.org is a rails site backed by MySQL, along with some
> clojure code to pull the namespaces / metadata / source and dump them
> into the database.
>
> Highlights:
> 1. Documentation and source for Clojure core, contrib, and a few third
> party libraries (random selection out of what I'm personally familiar
> with, and whatever was on the github trends page that day).
>
> 2. Search for a var across the whole ecosystem or in a specific
> library.
>
> 3. Per var wiki-style examples section.
>
> 4. Per var comments section.
>
> 5. Per var vars-in-this-var and this-var-used-in section (my personal
> favorite). Looking for a real-world example of a specific function?
> This is for you. For example,http://clojuredocs.org/v/1978, just
> examples database, along with solid search capabilities across both
> core and third party libraries (core being the focus).
>
> Implementation:
> ClojureDocs.org is a rails site backed by MySQL, along with some
> clojure code to pull the namespaces / metadata / source and dump them
> into the database.
>
> Highlights:
> 1. Documentation and source for Clojure core, contrib, and a few third
> party libraries (random selection out of what I'm personally familiar
> with, and whatever was on the github trends page that day).
>
> 2. Search for a var across the whole ecosystem or in a specific
> library.
>
> 3. Per var wiki-style examples section.
>
> 4. Per var comments section.
>
> 5. Per var vars-in-this-var and this-var-used-in section (my personal
> favorite). Looking for a real-world example of a specific function?
> below the source section.
>
> Lowlights:
> 1. Ugly URLs! There's a problem in the way that URLs with encoded
> question marks are being handled, so I had to move fromhttp://clojuredocs.org/clj-ssh/clj-ssh.core/file-pathtohttp://clojuredocs.org/v/1484. I've got an email out to the Phusion
>
> Lowlights:
> 1. Ugly URLs! There's a problem in the way that URLs with encoded
Justin Kramer
Jul 9, 2010, 2:44:46 PM7/9/10
to Clojure
I've told Zack that he is free to pull any examples from the wiki for
use on his site.
I don't know about collaboration beyond that. The wiki is open source
and written in Clojure; anyone is free to contribute/fork. At least
one person has expressed interest in making code contributions.
Zack, you had mentioned you planned to keep the source of your site
proprietary -- is that set in stone?
Justin
On Jul 9, 12:21 pm, David Nolen <dnolen.li...@gmail.com> wrote:
use on his site.
I don't know about collaboration beyond that. The wiki is open source
and written in Clojure; anyone is free to contribute/fork. At least
one person has expressed interest in making code contributions.
Zack, you had mentioned you planned to keep the source of your site
proprietary -- is that set in stone?
Justin
On Jul 9, 12:21 pm, David Nolen <dnolen.li...@gmail.com> wrote:
Tom Faulhaber
Jul 9, 2010, 4:06:37 PM7/9/10
to Clojure
Quick thought: You probably don't want to include private vars.
On Jul 9, 1:32 am, zkim <zachary....@gmail.com> wrote:
> Hi All,
>
> I'll try to keep this short.
>
> I've gotten a lot out of Clojure: I can honestly say that learning
> this language, and being part of this community has made me a better,
> happier developer, and I wanted to give something back.
>
> One of the pain points that I encountered when learning the language
> was a lack of examples specific to the individual functions I was
> trying to wrap my head around at any given time. So I took a whack at
> the problem, and came up withhttp://clojuredocs.org. It's a site
On Jul 9, 1:32 am, zkim <zachary....@gmail.com> wrote:
> Hi All,
>
> I'll try to keep this short.
>
> I've gotten a lot out of Clojure: I can honestly say that learning
> this language, and being part of this community has made me a better,
> happier developer, and I wanted to give something back.
>
> One of the pain points that I encountered when learning the language
> was a lack of examples specific to the individual functions I was
> trying to wrap my head around at any given time. So I took a whack at
> that (I'm hoping) will fill this need by providing a centralized
> examples database, along with solid search capabilities across both
> core and third party libraries (core being the focus).
>
> Implementation:
> ClojureDocs.org is a rails site backed by MySQL, along with some
> clojure code to pull the namespaces / metadata / source and dump them
> into the database.
>
> Highlights:
> 1. Documentation and source for Clojure core, contrib, and a few third
> party libraries (random selection out of what I'm personally familiar
> with, and whatever was on the github trends page that day).
>
> 2. Search for a var across the whole ecosystem or in a specific
> library.
>
> 3. Per var wiki-style examples section.
>
> 4. Per var comments section.
>
> 5. Per var vars-in-this-var and this-var-used-in section (my personal
> favorite). Looking for a real-world example of a specific function?
> This is for you. For example,http://clojuredocs.org/v/1978, just
> examples database, along with solid search capabilities across both
> core and third party libraries (core being the focus).
>
> Implementation:
> ClojureDocs.org is a rails site backed by MySQL, along with some
> clojure code to pull the namespaces / metadata / source and dump them
> into the database.
>
> Highlights:
> 1. Documentation and source for Clojure core, contrib, and a few third
> party libraries (random selection out of what I'm personally familiar
> with, and whatever was on the github trends page that day).
>
> 2. Search for a var across the whole ecosystem or in a specific
> library.
>
> 3. Per var wiki-style examples section.
>
> 4. Per var comments section.
>
> 5. Per var vars-in-this-var and this-var-used-in section (my personal
> favorite). Looking for a real-world example of a specific function?
> below the source section.
>
> Lowlights:
> 1. Ugly URLs! There's a problem in the way that URLs with encoded
> question marks are being handled, so I had to move fromhttp://clojuredocs.org/clj-ssh/clj-ssh.core/file-pathtohttp://clojuredocs.org/v/1484. I've got an email out to the Phusion
>
> Lowlights:
> 1. Ugly URLs! There's a problem in the way that URLs with encoded
Lee Hinman
Jul 9, 2010, 12:11:34 PM7/9/10
to clo...@googlegroups.com
zkim
Jul 9, 2010, 1:41:54 PM7/9/10
to Clojure
Thanks all for your kind words. As to the specifics:
> The headers for each section (Doc, Source, Example(s)) don't
> differentiate themselves from the regular doc text enough, maybe
> bold/underline/color them to make them show up more?
I'd agree, I think the visual styling of the page will change a lot in
the near future based on feedback, for now I'll add underlining.
> The links to the source code should link to
> http://github.com/clojure/clojure, I believe the richhickey clojure
> repo has been transitioned there.
Will update.
> I know non-confirmation logins are really nice, but should the site
> attract any spammers, you may want to look at adding an email account
> confirmation (since spammers could go nuts adding comments to pages).
This is strictly for alpha, I'm currently going back and forth between
signups confirmed through email, or recaptcha (or both), but rounding
out the sign-up / login process is high on my list.
> This is great. I think the main thing is not duplicating effort. This and
> clojure-examples.appspot.com should really join forces.
from his site (as well as given some great feedback). I'm definitely
all for a collaborative effort.
Thanks, Zack.
> The headers for each section (Doc, Source, Example(s)) don't
> differentiate themselves from the regular doc text enough, maybe
> bold/underline/color them to make them show up more?
the near future based on feedback, for now I'll add underlining.
> The links to the source code should link to
> http://github.com/clojure/clojure, I believe the richhickey clojure
> repo has been transitioned there.
> I know non-confirmation logins are really nice, but should the site
> attract any spammers, you may want to look at adding an email account
> confirmation (since spammers could go nuts adding comments to pages).
signups confirmed through email, or recaptcha (or both), but rounding
out the sign-up / login process is high on my list.
> This is great. I think the main thing is not duplicating effort. This and
> clojure-examples.appspot.com should really join forces.
> Having contributed a lot of examples to clojure-examples.appspot.com
> this week, I agree that it would be a shame to duplicate efforts.
I've been talking with Justin, and he's allowed me to pull examples
> this week, I agree that it would be a shame to duplicate efforts.
from his site (as well as given some great feedback). I'm definitely
all for a collaborative effort.
Thanks, Zack.
zkim
Jul 9, 2010, 2:52:46 PM7/9/10
to Clojure
I've put these suggestions up on the UserVoice page, I believe I got
all of them, but if I missed yours please add it yourself or let me
know.
Dimitri: I share your frustrations with having to remember yet another
login / password. Other than minor cosmetic fixes, improving the user
signup / login experience is at the top of my list.
Alex: Example lookup from the REPL would be awesome. As of now this
is a bit lower on the list until things stabilize around the site.
Side note: My responses don't seem to be showing up right away on the
mailing list, so they may appear out of order.
all of them, but if I missed yours please add it yourself or let me
know.
Dimitri: I share your frustrations with having to remember yet another
login / password. Other than minor cosmetic fixes, improving the user
signup / login experience is at the top of my list.
Alex: Example lookup from the REPL would be awesome. As of now this
is a bit lower on the list until things stabilize around the site.
Side note: My responses don't seem to be showing up right away on the
mailing list, so they may appear out of order.
zkim
Jul 9, 2010, 3:07:36 PM7/9/10
to Clojure
Hi Justin, thanks again for the go-ahead to pull examples from
http://clojure-examples.appspot.com.
> Zack, you had mentioned you planned to keep the source of your site
> proprietary -- is that set in stone?
Clojure going on there (rails / mysql), and I'd rather keep that part
closed for now so I can concentrate on moving from alpha to beta,
adding features, and fixing bugs. The analyzer, which pulls
metadata / source from libraries, and inserts it into the database is
a different story. Other than the fact that it's extremely hackish,
nothing's really stopping me from EPLing it in the near future.
You also mentioned an API / export process, which I think is a great
idea. This would allow examples to be easily exported to prevent
vendor lock-in.
-Zack
Gavin Heavyside
Jul 9, 2010, 3:19:14 PM7/9/10
to clo...@googlegroups.com
Looks really good to me. Could you display the version numbers for Clojure and the libraries that the site covers?
Gavin
John Cromartie
Jul 9, 2010, 4:55:33 PM7/9/10
to Clojure
Beautiful. I think this should become the official community place for
Clojure docs. Now who wants to integrate my :examples defn attribute
code :)
-John
On Jul 9, 4:32 am, zkim <zachary....@gmail.com> wrote:
> Hi All,
>
> I'll try to keep this short.
>
> I've gotten a lot out of Clojure: I can honestly say that learning
> this language, and being part of this community has made me a better,
> happier developer, and I wanted to give something back.
>
> One of the pain points that I encountered when learning the language
> was a lack of examples specific to the individual functions I was
> trying to wrap my head around at any given time. So I took a whack at
> the problem, and came up withhttp://clojuredocs.org. It's a site
Clojure docs. Now who wants to integrate my :examples defn attribute
code :)
-John
On Jul 9, 4:32 am, zkim <zachary....@gmail.com> wrote:
> Hi All,
>
> I'll try to keep this short.
>
> I've gotten a lot out of Clojure: I can honestly say that learning
> this language, and being part of this community has made me a better,
> happier developer, and I wanted to give something back.
>
> One of the pain points that I encountered when learning the language
> was a lack of examples specific to the individual functions I was
> trying to wrap my head around at any given time. So I took a whack at
> that (I'm hoping) will fill this need by providing a centralized
> examples database, along with solid search capabilities across both
> core and third party libraries (core being the focus).
>
> Implementation:
> ClojureDocs.org is a rails site backed by MySQL, along with some
> clojure code to pull the namespaces / metadata / source and dump them
> into the database.
>
> Highlights:
> 1. Documentation and source for Clojure core, contrib, and a few third
> party libraries (random selection out of what I'm personally familiar
> with, and whatever was on the github trends page that day).
>
> 2. Search for a var across the whole ecosystem or in a specific
> library.
>
> 3. Per var wiki-style examples section.
>
> 4. Per var comments section.
>
> 5. Per var vars-in-this-var and this-var-used-in section (my personal
> favorite). Looking for a real-world example of a specific function?
> This is for you. For example,http://clojuredocs.org/v/1978, just
> examples database, along with solid search capabilities across both
> core and third party libraries (core being the focus).
>
> Implementation:
> ClojureDocs.org is a rails site backed by MySQL, along with some
> clojure code to pull the namespaces / metadata / source and dump them
> into the database.
>
> Highlights:
> 1. Documentation and source for Clojure core, contrib, and a few third
> party libraries (random selection out of what I'm personally familiar
> with, and whatever was on the github trends page that day).
>
> 2. Search for a var across the whole ecosystem or in a specific
> library.
>
> 3. Per var wiki-style examples section.
>
> 4. Per var comments section.
>
> 5. Per var vars-in-this-var and this-var-used-in section (my personal
> favorite). Looking for a real-world example of a specific function?
> below the source section.
>
> Lowlights:
> 1. Ugly URLs! There's a problem in the way that URLs with encoded
> question marks are being handled, so I had to move fromhttp://clojuredocs.org/clj-ssh/clj-ssh.core/file-pathtohttp://clojuredocs.org/v/1484. I've got an email out to the Phusion
>
> Lowlights:
> 1. Ugly URLs! There's a problem in the way that URLs with encoded
zkim
Jul 9, 2010, 5:47:20 PM7/9/10
to Clojure
Tom-
I kind of went back and forth on this. Originally I only parsed out
public vars, but in a couple of instances I found that when tracing
through some code I would hit on private vars.
Perhaps a solution where private vars are hidden from normal flow
(browsing and searching) unless explicitly included by the user?
-Zack
> > question marks are being handled, so I had to move fromhttp://clojuredocs.org/clj-ssh/clj-ssh.core/file-pathtohttp://clojure.... I've got an email out to the Phusion
I kind of went back and forth on this. Originally I only parsed out
public vars, but in a couple of instances I found that when tracing
through some code I would hit on private vars.
Perhaps a solution where private vars are hidden from normal flow
(browsing and searching) unless explicitly included by the user?
-Zack
Justin Kramer
Jul 9, 2010, 7:05:54 PM7/9/10
to Clojure
An "examples" function for the REPL that pulls from the wiki:
http://gist.github.com/470031
I'm sure something like it could be made for ClojureDocs.org once the
API is in place.
General comments on ClojureDocs.org: I think an important aspect of a
collaborative tool like this is quality control. There needs to be
people watching recent updates, making sure examples meet certain
standards (formatted correctly, idiomatic, etc.). To that end, a
complete list of recent updates (with diffs) to go along with the
short list on the homepage would be really nice.
Having a category-based outlines would also be nice. I have one here
for clojure.core, adapted from the Cheatsheet:
http://clojure-examples.appspot.com/clojure.core
Feel free to nab it.
FYI, I'll probably be implementing a mass export feature for the wiki,
so you could write a script or something to automate an import.
Awesome work, Zack.
Justin
> > question marks are being handled, so I had to move fromhttp://clojuredocs.org/clj-ssh/clj-ssh.core/file-pathtohttp://clojure.... I've got an email out to the Phusion
http://gist.github.com/470031
I'm sure something like it could be made for ClojureDocs.org once the
API is in place.
General comments on ClojureDocs.org: I think an important aspect of a
collaborative tool like this is quality control. There needs to be
people watching recent updates, making sure examples meet certain
standards (formatted correctly, idiomatic, etc.). To that end, a
complete list of recent updates (with diffs) to go along with the
short list on the homepage would be really nice.
Having a category-based outlines would also be nice. I have one here
for clojure.core, adapted from the Cheatsheet:
http://clojure-examples.appspot.com/clojure.core
Feel free to nab it.
FYI, I'll probably be implementing a mass export feature for the wiki,
so you could write a script or something to automate an import.
Awesome work, Zack.
Justin
Greg
Jul 9, 2010, 7:23:23 PM7/9/10
to clo...@googlegroups.com
*argh*. well at least my email is now finally on the whitelist.
What do you guys think of some of the ideas presented in the "Solving Clojure's Documentation Problem Without Fragmentation" thread? (Which I sent shortly after this thread started, but ended up being posted several hours later).
https://groups.google.com/group/clojure/t/77fda1c7c95f5344
- Greg
P.S. clojuredoc.org might be irrelevant if you guys choose to collaborate on the same project, but what do you think about using Justin's codebase, or an Aleph-based server to host the thing instead of Ruby/Rails? (see the link above for more details)
Meikel Brandmeyer
Jul 10, 2010, 1:57:33 AM7/10/10
to clo...@googlegroups.com
Hi,
Am 09.07.2010 um 23:47 schrieb zkim:
> I kind of went back and forth on this. Originally I only parsed out
> public vars, but in a couple of instances I found that when tracing
> through some code I would hit on private vars.
I'm suspicious of showing source code to the reader with everything more than a small quite nondescript link. The contract is the docstring. Looking at the code might be interesting but non-helpful. You start relying on implementation details, while these might change at any time (eg. introduction of transients, etc.). I would *not* show the source code and I would *not* document private vars. They are not part of the contract and should not show up in public API documentation.
Sincerely
Meikel
Heinz N. Gies
Jul 10, 2010, 5:11:29 AM7/10/10
to clo...@googlegroups.com
Hi Zack,
first of all, great effort there :) having a place for clojure docs is awesome. Two things come to mind:
first of all, great effort there :) having a place for clojure docs is awesome. Two things come to mind:
1) http://github.com/defn/walton - have a look at it, it might be a good way to fetch examples for functions where none are provided yet.
2) Will it be possible to put other 3rd party libs on there - since I'd like to add some of mine, it's likely better to have them documented centrally then keeping a own documentation for each library. :)
Regards,
Heinz
Shantanu Kumar
Jul 10, 2010, 5:29:07 AM7/10/10
to Clojure
This is great. One suggestion -- consider providing a downloadable
bundle for offline use as well.
Regards,
Shantanu
On Jul 10, 2:11 pm, "Heinz N. Gies" <he...@licenser.net> wrote:
> Hi Zack,
> first of all, great effort there :) having a place for clojure docs is awesome. Two things come to mind:
>
> 1)http://github.com/defn/walton- have a look at it, it might be a good way to fetch examples for functions where none are provided yet.
bundle for offline use as well.
Regards,
Shantanu
On Jul 10, 2:11 pm, "Heinz N. Gies" <he...@licenser.net> wrote:
> Hi Zack,
> first of all, great effort there :) having a place for clojure docs is awesome. Two things come to mind:
>
RobertLJ
Jul 9, 2010, 11:47:31 PM7/9/10
to Clojure
This is GREAT!!! I love the way you have opened it up for community
participation.
Robert
On Jul 9, 4:32 am, zkim <zachary....@gmail.com> wrote:
> Hi All,
>
> I'll try to keep this short.
>
> I've gotten a lot out of Clojure: I can honestly say that learning
> this language, and being part of this community has made me a better,
> happier developer, and I wanted to give something back.
>
> One of the pain points that I encountered when learning the language
> was a lack of examples specific to the individual functions I was
> trying to wrap my head around at any given time. So I took a whack at
> the problem, and came up withhttp://clojuredocs.org. It's a site
participation.
Robert
On Jul 9, 4:32 am, zkim <zachary....@gmail.com> wrote:
> Hi All,
>
> I'll try to keep this short.
>
> I've gotten a lot out of Clojure: I can honestly say that learning
> this language, and being part of this community has made me a better,
> happier developer, and I wanted to give something back.
>
> One of the pain points that I encountered when learning the language
> was a lack of examples specific to the individual functions I was
> trying to wrap my head around at any given time. So I took a whack at
> that (I'm hoping) will fill this need by providing a centralized
> examples database, along with solid search capabilities across both
> core and third party libraries (core being the focus).
>
> Implementation:
> ClojureDocs.org is a rails site backed by MySQL, along with some
> clojure code to pull the namespaces / metadata / source and dump them
> into the database.
>
> Highlights:
> 1. Documentation and source for Clojure core, contrib, and a few third
> party libraries (random selection out of what I'm personally familiar
> with, and whatever was on the github trends page that day).
>
> 2. Search for a var across the whole ecosystem or in a specific
> library.
>
> 3. Per var wiki-style examples section.
>
> 4. Per var comments section.
>
> 5. Per var vars-in-this-var and this-var-used-in section (my personal
> favorite). Looking for a real-world example of a specific function?
> This is for you. For example,http://clojuredocs.org/v/1978, just
> examples database, along with solid search capabilities across both
> core and third party libraries (core being the focus).
>
> Implementation:
> ClojureDocs.org is a rails site backed by MySQL, along with some
> clojure code to pull the namespaces / metadata / source and dump them
> into the database.
>
> Highlights:
> 1. Documentation and source for Clojure core, contrib, and a few third
> party libraries (random selection out of what I'm personally familiar
> with, and whatever was on the github trends page that day).
>
> 2. Search for a var across the whole ecosystem or in a specific
> library.
>
> 3. Per var wiki-style examples section.
>
> 4. Per var comments section.
>
> 5. Per var vars-in-this-var and this-var-used-in section (my personal
> favorite). Looking for a real-world example of a specific function?
> below the source section.
>
> Lowlights:
> 1. Ugly URLs! There's a problem in the way that URLs with encoded
> question marks are being handled, so I had to move fromhttp://clojuredocs.org/clj-ssh/clj-ssh.core/file-pathtohttp://clojuredocs.org/v/1484. I've got an email out to the Phusion
>
> Lowlights:
> 1. Ugly URLs! There's a problem in the way that URLs with encoded
James Reeves
Jul 10, 2010, 8:45:08 AM7/10/10
to clo...@googlegroups.com
On 9 July 2010 21:06, Tom Faulhaber <tomfau...@gmail.com> wrote:
> Quick thought: You probably don't want to include private vars.
> Quick thought: You probably don't want to include private vars.
Seconded. It's a little confusing seeing private vars and macros in
the API docs!
Other than that, this looks excellent. I'm signing up as I write this.
- James
Stuart Halloway
Jul 10, 2010, 10:06:30 AM7/10/10
to clo...@googlegroups.com
Very cool. Let me start by saying thanks to everyone who has been involved in the various threads on improving documentation, especially those who, like Zack, have taken substantial action.
Here are a bunch of ideas, in no particular order:
(1) Ease of contribution is huge, and http://clojuredocs.org looks good on this front. Stick to it.
(2) +1 on hiding private APIs. We use private APIs carefully and deliberately in Clojure, and I would hate to facilitate people writing code that will break later.
(3) +1 on making it very easy to see which version of an API you are looking at. This should be both at the top level (some way to say "show me 1.1") and on a per-var basis, reading the :added metadata.
(4) Provenance matters. Clojure itself is very careful to have people sign a CA before contributing code. The bar may be somewhat different for a documentation site, but it still needs to be carefully considered.
(5) Continuity matters. We have already had some pain with useful resources popping up on the web and then having the maintainer go AWOL with no succession plan. There are several steps any documentation site should take to address this: (a) open sourcing everything (b) including multiple committers and admins on the site itself and (c) providing an easy API to suck the data out.
(6) Because docstrings are designed for consumption at a REPL, they may in some cases presume a fixed font. Worth considering for display on the site.
(7) Quality matters. There are multiple possible ways to make sure that the cream rises: letting people up and downvote, making it easy for "editors" to track new submissions, etc.
Thanks again!
Stu
James Reeves
Jul 10, 2010, 1:36:40 PM7/10/10
to clo...@googlegroups.com
On 10 July 2010 15:06, Stuart Halloway <stuart....@gmail.com> wrote:
> (6) Because docstrings are designed for consumption at a REPL, they may in some cases presume a fixed font. Worth considering for display on the site.
> (6) Because docstrings are designed for consumption at a REPL, they may in some cases presume a fixed font. Worth considering for display on the site.
What about giving function documentation the same "wiki" behaviour
that the examples have? Start off with the docstrings as the initial
values, but allow people to update them. The web allows longer and
better formatted documentation than a standard Clojure docstring
(which needs to fit in a terminal).
- James
Luc Préfontaine
Jul 10, 2010, 2:58:52 PM7/10/10
to clo...@googlegroups.com
Zack if you need help with this Rail
app let us now. We can give you a
hand, the wish list keeps growing :)))
app let us now. We can give you a
hand, the wish list keeps growing :)))
Luc P.
Sent from my iPod
zkim
Jul 11, 2010, 1:51:14 AM7/11/10
to Clojure
> http://gist.github.com/470031
>
> I'm sure something like it could be made for ClojureDocs.org once the
> API is in place.
Nice, looks pretty straightforward.
>
> I'm sure something like it could be made for ClojureDocs.org once the
> API is in place.
> I think an important aspect of a
> complete list of recent updates (with diffs) to go along with the
> short list on the homepage would be really nice.
Agreed. I'd like to have an in depth discussion around this issue, and
> short list on the homepage would be really nice.
what potential solutions would look like, so I've set up google group
(http://groups.google.com/group/clojuredocsorg). I'll be seeding this
form with a couple of posts later tonight revolving around what I feel
are some core issues that are very important to get right, and
therefore require community facing discussion.
> Having a category-based outlines would also be nice. I have one here
> for clojure.core, adapted from the Cheatsheet:
>
> http://clojure-examples.appspot.com/clojure.core
> FYI, I'll probably be implementing a mass export feature for the wiki,
> so you could write a script or something to automate an import.
-Zack
zkim
Jul 11, 2010, 2:23:49 AM7/11/10
to Clojure
Greg-
I'd like to take the time to look over the post you linked in-depth
before responding.
> but what do you think about using Justin's codebase, or an Aleph-based server to
> host the thing instead of Ruby/Rails? (see the link above for more details)
I'm inclined to move forward with the Ruby / Rails for now. The
reason I went with rails is that (in my experience) none of the
clojure web libraries are mature enough to do something like
clojuredocs as quickly and easily as I personally would be able to do
in rails.
I'd like to be explicit here: I think the work that cgrand, mmcgrana,
weavejester, brentonashworth, et al is amazing. I will be the first to
get a big fat lambda tattoo on my forehead once the day comes that I
can do all my web dev stuff in Clojure (please nobody hold me to
this), but I'd like to wait till the web space matures a bit more
before porting it over.
The bottom line here is that I'd like to deliver the best possible
user experience that I can, and as of right now that means a rails
based solution.
-Zack
I'd like to take the time to look over the post you linked in-depth
before responding.
> but what do you think about using Justin's codebase, or an Aleph-based server to
> host the thing instead of Ruby/Rails? (see the link above for more details)
reason I went with rails is that (in my experience) none of the
clojure web libraries are mature enough to do something like
clojuredocs as quickly and easily as I personally would be able to do
in rails.
I'd like to be explicit here: I think the work that cgrand, mmcgrana,
weavejester, brentonashworth, et al is amazing. I will be the first to
get a big fat lambda tattoo on my forehead once the day comes that I
can do all my web dev stuff in Clojure (please nobody hold me to
this), but I'd like to wait till the web space matures a bit more
before porting it over.
The bottom line here is that I'd like to deliver the best possible
user experience that I can, and as of right now that means a rails
based solution.
-Zack
zkim
Jul 11, 2010, 2:38:25 AM7/11/10
to Clojure
Heinz-
> first of all, great effort there :) having a place for clojure docs is awesome.
Thanks, appreciated.
> 1) http://github.com/defn/walton - have a look at it, it might be a
> good way to fetch examples for functions where none are provided yet.
I'll take a look.
> 2) Will it be possible to put other 3rd party libs on there - since I'd
> like to add some of mine, it's likely better to have them documented
> centrally then keeping a own documentation for each library. :)
For now send me an email with a link to the repo, as well as any
categorization suggestions you have for your lib. Ultimately I'd
like to get clojuredocs.org to the point where you can enter a repo
url into a web form and click 'add / update' (or maybe some code that
watches a repo for updates).
On Jul 10, 3:11 am, "Heinz N. Gies" <he...@licenser.net> wrote:
> Hi Zack,
> first of all, great effort there :) having a place for clojure docs is awesome. Two things come to mind:
>
> 1)http://github.com/defn/walton- have a look at it, it might be a good way to fetch examples for functions where none are provided yet.
> first of all, great effort there :) having a place for clojure docs is awesome.
> 1) http://github.com/defn/walton - have a look at it, it might be a
> good way to fetch examples for functions where none are provided yet.
> 2) Will it be possible to put other 3rd party libs on there - since I'd
> like to add some of mine, it's likely better to have them documented
> centrally then keeping a own documentation for each library. :)
categorization suggestions you have for your lib. Ultimately I'd
like to get clojuredocs.org to the point where you can enter a repo
url into a web form and click 'add / update' (or maybe some code that
watches a repo for updates).
On Jul 10, 3:11 am, "Heinz N. Gies" <he...@licenser.net> wrote:
> Hi Zack,
> first of all, great effort there :) having a place for clojure docs is awesome. Two things come to mind:
>
zkim
Jul 11, 2010, 2:57:14 AM7/11/10
to Clojure
Shantanu-
> One suggestion -- consider providing a downloadable
> bundle for offline use as well.
I believe there's an item up on the UserVoice page (http://
clojuredocs.uservoice.com/) keep an eye out for updates and comments
there.
-Zack
On Jul 10, 3:29 am, Shantanu Kumar <kumar.shant...@gmail.com> wrote:
> This is great. One suggestion -- consider providing a downloadable
> bundle for offline use as well.
>
> Regards,
> Shantanu
>
> On Jul 10, 2:11 pm, "Heinz N. Gies" <he...@licenser.net> wrote:
>
>
>
> > Hi Zack,
> > first of all, great effort there :) having a place for clojure docs is awesome. Two things come to mind:
>
> > 1)http://github.com/defn/walton-have a look at it, it might be a good way to fetch examples for functions where none are provided yet.
> One suggestion -- consider providing a downloadable
> bundle for offline use as well.
clojuredocs.uservoice.com/) keep an eye out for updates and comments
there.
-Zack
On Jul 10, 3:29 am, Shantanu Kumar <kumar.shant...@gmail.com> wrote:
> This is great. One suggestion -- consider providing a downloadable
> bundle for offline use as well.
>
> Regards,
> Shantanu
>
> On Jul 10, 2:11 pm, "Heinz N. Gies" <he...@licenser.net> wrote:
>
>
>
> > Hi Zack,
> > first of all, great effort there :) having a place for clojure docs is awesome. Two things come to mind:
>
zkim
Jul 11, 2010, 5:23:13 AM7/11/10
to Clojure
Stu-
> (2) +1 on hiding private APIs. We use private APIs carefully and
> deliberately in Clojure, and I would hate to facilitate people
> writing code that will break later.
That's +4 on this one by my tally, I'll pull the private vars.
> (3) +1 on making it very easy to see which version of an API
> you are looking at. This should be both at the top level (some
> way to say "show me 1.1") and on a per-var basis, reading
> the :added metadata.
This is something I'd like to discuss in-depth on the new google group
(http://groups.google.com/group/clojuredocsorg). It is something that
I'd really like to see, but I haven't worked through the
implementation details in my head (multiple versions stored per var
vs. diffs stored, UI around this, etc).
> (4) Provenance matters. Clojure itself is very careful to have
> people sign a CA before contributing code. The bar may be
> somewhat different for a documentation site, but it still needs
> to be carefully considered.
My first thought was to add some copy somewhere stating something to
the effect of "By adding content to this site you are allowing said
content to be licensed under the EPL." My second thought was that I'm
not a lawyer :). Jokes aside, I agree that this is an important
matter, and while the exact mechanism to accomplish this is unclear to
me, the direct effect is not: I'd like users to be able to freely add
to, copy, and modify any user generated content to facilitate learning
the Clojure language and its libraries.
> (5) Continuity matters. We have already had some pain with useful
> resources popping up on the web and then having the maintainer go
> AWOL with no succession plan. There are several steps any
> documentation site should take to address this: (a) open sourcing
> everything (b) including multiple committers and admins on the site
> itself and (c) providing an easy API to suck the data out.
If I had to map this out right now I'd say the order of operations
within the scope of this point would be (c), then (a), then (b), and
all after locking down the provenance issue you outlined above. I
believe Justin also had concerns around this issue, and I think the
short answer is that the amount of pain is going to be inversely
proportional to time, but I'm committed to taking whatever measures
are necessary to ensure that the hard work that went into adding
content to the site would not be lost. I'll start a thread over at
the clojuredocs.org group to discuss this.
> Because docstrings are designed for consumption at a REPL,
> they may in some cases presume a fixed font. Worth considering
> for display on the site.
Sounds good, fix is up on the site.
> Quality matters. There are multiple possible ways to make sure
> that the cream rises: letting people up and downvote, making it
> easy for "editors" to track new submissions, etc.
I think a mix of community and 'admin / editor' influence would be
great here. Initially I'd like to provide an RSS feed for additions /
changes to examples and comments. It's difficult to guess down the
line because of the nature of the other issues that are up in the air
right now, but I think we'll figure something out.
Thanks again for the feedback. I think you've framed some important
discussions about clojuredocs.org, and community documentation in
general.
-Zack
On Jul 10, 8:06 am, Stuart Halloway <stuart.hallo...@gmail.com> wrote:
> Very cool. Let me start by saying thanks to everyone who has been involved in the various threads on improving documentation, especially those who, like Zack, have taken substantial action.
>
> Here are a bunch of ideas, in no particular order:
>
> (1) Ease of contribution is huge, andhttp://clojuredocs.orglooks good on this front. Stick to it.
> (2) +1 on hiding private APIs. We use private APIs carefully and
> deliberately in Clojure, and I would hate to facilitate people
> writing code that will break later.
> (3) +1 on making it very easy to see which version of an API
> you are looking at. This should be both at the top level (some
> way to say "show me 1.1") and on a per-var basis, reading
> the :added metadata.
(http://groups.google.com/group/clojuredocsorg). It is something that
I'd really like to see, but I haven't worked through the
implementation details in my head (multiple versions stored per var
vs. diffs stored, UI around this, etc).
> (4) Provenance matters. Clojure itself is very careful to have
> people sign a CA before contributing code. The bar may be
> somewhat different for a documentation site, but it still needs
> to be carefully considered.
the effect of "By adding content to this site you are allowing said
content to be licensed under the EPL." My second thought was that I'm
not a lawyer :). Jokes aside, I agree that this is an important
matter, and while the exact mechanism to accomplish this is unclear to
me, the direct effect is not: I'd like users to be able to freely add
to, copy, and modify any user generated content to facilitate learning
the Clojure language and its libraries.
> (5) Continuity matters. We have already had some pain with useful
> resources popping up on the web and then having the maintainer go
> AWOL with no succession plan. There are several steps any
> documentation site should take to address this: (a) open sourcing
> everything (b) including multiple committers and admins on the site
> itself and (c) providing an easy API to suck the data out.
within the scope of this point would be (c), then (a), then (b), and
all after locking down the provenance issue you outlined above. I
believe Justin also had concerns around this issue, and I think the
short answer is that the amount of pain is going to be inversely
proportional to time, but I'm committed to taking whatever measures
are necessary to ensure that the hard work that went into adding
content to the site would not be lost. I'll start a thread over at
the clojuredocs.org group to discuss this.
> Because docstrings are designed for consumption at a REPL,
> they may in some cases presume a fixed font. Worth considering
> for display on the site.
> Quality matters. There are multiple possible ways to make sure
> that the cream rises: letting people up and downvote, making it
> easy for "editors" to track new submissions, etc.
great here. Initially I'd like to provide an RSS feed for additions /
changes to examples and comments. It's difficult to guess down the
line because of the nature of the other issues that are up in the air
right now, but I think we'll figure something out.
Thanks again for the feedback. I think you've framed some important
discussions about clojuredocs.org, and community documentation in
general.
-Zack
On Jul 10, 8:06 am, Stuart Halloway <stuart.hallo...@gmail.com> wrote:
> Very cool. Let me start by saying thanks to everyone who has been involved in the various threads on improving documentation, especially those who, like Zack, have taken substantial action.
>
> Here are a bunch of ideas, in no particular order:
>
>
> (2) +1 on hiding private APIs. We use private APIs carefully and deliberately in Clojure, and I would hate to facilitate people writing code that will break later.
>
> (3) +1 on making it very easy to see which version of an API you are looking at. This should be both at the top level (some way to say "show me 1.1") and on a per-var basis, reading the :added metadata.
>
> (4) Provenance matters. Clojure itself is very careful to have people sign a CA before contributing code. The bar may be somewhat different for a documentation site, but it still needs to be carefully considered.
>
> (5) Continuity matters. We have already had some pain with useful resources popping up on the web and then having the maintainer go AWOL with no succession plan. There are several steps any documentation site should take to address this: (a) open sourcing everything (b) including multiple committers and admins on the site itself and (c) providing an easy API to suck the data out.
>
> (6) Because docstrings are designed for consumption at a REPL, they may in some cases presume a fixed font. Worth considering for display on the site.
>
> (7) Quality matters. There are multiple possible ways to make sure that the cream rises: letting people up and downvote, making it easy for "editors" to track new submissions, etc.
>
> Thanks again!
>
> Stu
>
>
>
> > Hi All,
>
> > I'll try to keep this short.
>
> > I've gotten a lot out of Clojure: I can honestly say that learning
> > this language, and being part of this community has made me a better,
> > happier developer, and I wanted to give something back.
>
> > One of the pain points that I encountered when learning the language
> > was a lack of examples specific to the individual functions I was
> > trying to wrap my head around at any given time. So I took a whack at
> > the problem, and came up withhttp://clojuredocs.org. It's a site
> (2) +1 on hiding private APIs. We use private APIs carefully and deliberately in Clojure, and I would hate to facilitate people writing code that will break later.
>
> (3) +1 on making it very easy to see which version of an API you are looking at. This should be both at the top level (some way to say "show me 1.1") and on a per-var basis, reading the :added metadata.
>
> (4) Provenance matters. Clojure itself is very careful to have people sign a CA before contributing code. The bar may be somewhat different for a documentation site, but it still needs to be carefully considered.
>
> (5) Continuity matters. We have already had some pain with useful resources popping up on the web and then having the maintainer go AWOL with no succession plan. There are several steps any documentation site should take to address this: (a) open sourcing everything (b) including multiple committers and admins on the site itself and (c) providing an easy API to suck the data out.
>
> (6) Because docstrings are designed for consumption at a REPL, they may in some cases presume a fixed font. Worth considering for display on the site.
>
> (7) Quality matters. There are multiple possible ways to make sure that the cream rises: letting people up and downvote, making it easy for "editors" to track new submissions, etc.
>
> Thanks again!
>
> Stu
>
>
>
> > Hi All,
>
> > I'll try to keep this short.
>
> > I've gotten a lot out of Clojure: I can honestly say that learning
> > this language, and being part of this community has made me a better,
> > happier developer, and I wanted to give something back.
>
> > One of the pain points that I encountered when learning the language
> > was a lack of examples specific to the individual functions I was
> > trying to wrap my head around at any given time. So I took a whack at
> > that (I'm hoping) will fill this need by providing a centralized
> > examples database, along with solid search capabilities across both
> > core and third party libraries (core being the focus).
>
> > Implementation:
> > ClojureDocs.org is a rails site backed by MySQL, along with some
> > clojure code to pull the namespaces / metadata / source and dump them
> > into the database.
>
> > Highlights:
> > 1. Documentation and source for Clojure core, contrib, and a few third
> > party libraries (random selection out of what I'm personally familiar
> > with, and whatever was on the github trends page that day).
>
> > 2. Search for a var across the whole ecosystem or in a specific
> > library.
>
> > 3. Per var wiki-style examples section.
>
> > 4. Per var comments section.
>
> > 5. Per var vars-in-this-var and this-var-used-in section (my personal
> > favorite). Looking for a real-world example of a specific function?
> > This is for you. For example,http://clojuredocs.org/v/1978, just
> > examples database, along with solid search capabilities across both
> > core and third party libraries (core being the focus).
>
> > Implementation:
> > ClojureDocs.org is a rails site backed by MySQL, along with some
> > clojure code to pull the namespaces / metadata / source and dump them
> > into the database.
>
> > Highlights:
> > 1. Documentation and source for Clojure core, contrib, and a few third
> > party libraries (random selection out of what I'm personally familiar
> > with, and whatever was on the github trends page that day).
>
> > 2. Search for a var across the whole ecosystem or in a specific
> > library.
>
> > 3. Per var wiki-style examples section.
>
> > 4. Per var comments section.
>
> > 5. Per var vars-in-this-var and this-var-used-in section (my personal
> > favorite). Looking for a real-world example of a specific function?
Phil Hagelberg
Jul 11, 2010, 10:14:21 AM7/11/10
to clo...@googlegroups.com
On Sat, Jul 10, 2010 at 11:23 PM, zkim <zacha...@gmail.com> wrote:
>> but what do you think about using Justin's codebase, or an Aleph-based server to
>> host the thing instead of Ruby/Rails? (see the link above for more details)
>
> I'm inclined to move forward with the Ruby / Rails for now. The
> reason I went with rails is that (in my experience) none of the
> clojure web libraries are mature enough to do something like
> clojuredocs as quickly and easily as I personally would be able to do
> in rails.
>> but what do you think about using Justin's codebase, or an Aleph-based server to
>> host the thing instead of Ruby/Rails? (see the link above for more details)
>
> I'm inclined to move forward with the Ruby / Rails for now. The
> reason I went with rails is that (in my experience) none of the
> clojure web libraries are mature enough to do something like
> clojuredocs as quickly and easily as I personally would be able to do
> in rails.
Could you provide details about what it was specifically that you
found was lacking?
-Phil
Lukasz Urbanek
Jul 11, 2010, 7:05:25 AM7/11/10
to Clojure
Looks very nice!
Hoping for the categories to arrive to the core namespace. This really
saves a lot of time for a clojure beginner like me.
Additionally, I'd prefer if the source was wasn't exposed by default
(It's quite distracting when one is looking for the examples), some
kind of "source" button that reveals it would be cool.
Hoping for the categories to arrive to the core namespace. This really
saves a lot of time for a clojure beginner like me.
Additionally, I'd prefer if the source was wasn't exposed by default
(It's quite distracting when one is looking for the examples), some
kind of "source" button that reveals it would be cool.
Richard Lyman
Jul 11, 2010, 2:37:07 PM7/11/10
to clo...@googlegroups.com
It sounded to me like he was only saying that he's more familiar with
Ruby/Rails than he is with Clojure. It seemed like it was a question
of 'time to finish and tweak' that's shortest for him if he wrote it
in Ruby/Rails.
Maybe this is a good opportunity to be able to compare two
implementations side-by-side. His excellent solution with one written
in Clojure that produces the same-ish website.
-Rich
zkim
Jul 11, 2010, 7:10:32 PM7/11/10
to Clojure
Phil-
A little background on my clojure web experience: I've got a intranet
web tool written using ring / enlive / moustache (system health /
monitoring for a personal project) as well as dabbled in compojure
before the 0.4.0 rev, and more recently I've been looking at sandbar /
carte. The timeframe for which I last took a serious look at Clojure
web technologies was April - May of this year (2010).
I'd say there were four main reasons why I chose to use rails over a
Clojure based solution:
1. Personal ease of feature implementation: This is part personal past
experience, part community support. I have some experience in rails,
and other rails-like frameworks. As far as community goes, every
problem (except the Passenger question mark problem I'm currently
having) there was a googleable solution that I found, or at least a
discussion that I could use to learn about the problem I was having,
consensuses on best practices, etc.
2. Persistence. For that monitoring intranet app I mentioned above
I'm using clojure.contrib.sql to make one-off connections to some
relatively simple schemas (log entries, no relations). A moderately
complex schema would have throw me for a loop using clojure.
3. Sessions using ring handlers. These were a problem for me, but I
think my handler mental model is broken.
4. Ecosystem. Tons of gems, plugins. Great for getting the broad
strokes down.
If you're willing to continue the discussion, I'd like to keep this
going (maybe another thread?). As I'm writing this I'm getting the
feeling that I'm not quite articulating my thoughts well, and I think
further discussion will help me to flesh them out.
Again, I'm really excited about the amazing progress that's been made
in the Clojure web space (even just since May). It's a tough problem
to get right, and I'm definitely willing to help those that have taken
up this difficult challenge any way I can.
-Zack
On Jul 11, 8:14 am, Phil Hagelberg <p...@hagelb.org> wrote:
A little background on my clojure web experience: I've got a intranet
web tool written using ring / enlive / moustache (system health /
monitoring for a personal project) as well as dabbled in compojure
before the 0.4.0 rev, and more recently I've been looking at sandbar /
carte. The timeframe for which I last took a serious look at Clojure
web technologies was April - May of this year (2010).
I'd say there were four main reasons why I chose to use rails over a
Clojure based solution:
1. Personal ease of feature implementation: This is part personal past
experience, part community support. I have some experience in rails,
and other rails-like frameworks. As far as community goes, every
problem (except the Passenger question mark problem I'm currently
having) there was a googleable solution that I found, or at least a
discussion that I could use to learn about the problem I was having,
consensuses on best practices, etc.
2. Persistence. For that monitoring intranet app I mentioned above
I'm using clojure.contrib.sql to make one-off connections to some
relatively simple schemas (log entries, no relations). A moderately
complex schema would have throw me for a loop using clojure.
3. Sessions using ring handlers. These were a problem for me, but I
think my handler mental model is broken.
4. Ecosystem. Tons of gems, plugins. Great for getting the broad
strokes down.
If you're willing to continue the discussion, I'd like to keep this
going (maybe another thread?). As I'm writing this I'm getting the
feeling that I'm not quite articulating my thoughts well, and I think
further discussion will help me to flesh them out.
Again, I'm really excited about the amazing progress that's been made
in the Clojure web space (even just since May). It's a tough problem
to get right, and I'm definitely willing to help those that have taken
up this difficult challenge any way I can.
-Zack
On Jul 11, 8:14 am, Phil Hagelberg <p...@hagelb.org> wrote:
zkim
Jul 11, 2010, 7:25:12 PM7/11/10
to Clojure
Lukasz-
> Hoping for the categories to arrive to the core namespace. This really
> saves a lot of time for a clojure beginner like me.
The way Justin did this is great (http://clojure-examples.appspot.com/
clojure.core). I'm hoping to add this in the near future.
> Additionally, I'd prefer if the source was wasn't exposed by default
> (It's quite distracting when one is looking for the examples), some
> kind of "source" button that reveals it would be cool.
There have been several other comments on clarifying the visual style
of the var pages. I'm going to roll this suggestion into those on the
UserVoice page.
-Zack
> Hoping for the categories to arrive to the core namespace. This really
> saves a lot of time for a clojure beginner like me.
clojure.core). I'm hoping to add this in the near future.
> Additionally, I'd prefer if the source was wasn't exposed by default
> (It's quite distracting when one is looking for the examples), some
> kind of "source" button that reveals it would be cool.
of the var pages. I'm going to roll this suggestion into those on the
UserVoice page.
-Zack
zkim
Jul 11, 2010, 7:31:29 PM7/11/10
to Clojure
Rich-
> It sounded to me like he was only saying that he's more familiar with
> Ruby/Rails than he is with Clojure.
Correct. I think it was a fair question, and I'm happy to provide
insights into my decision making process.
-Zack
On Jul 11, 12:37 pm, Richard Lyman <richard.ly...@gmail.com> wrote:
> On Sun, Jul 11, 2010 at 8:14 AM, Phil Hagelberg <p...@hagelb.org> wrote:
> It sounded to me like he was only saying that he's more familiar with
> Ruby/Rails than he is with Clojure.
insights into my decision making process.
-Zack
On Jul 11, 12:37 pm, Richard Lyman <richard.ly...@gmail.com> wrote:
> On Sun, Jul 11, 2010 at 8:14 AM, Phil Hagelberg <p...@hagelb.org> wrote:
Luc Préfontaine
Jul 11, 2010, 8:18:40 PM7/11/10
to clo...@googlegroups.com
We use Rails for all our GUIs,
we need simple CRUD most of
the time and we ActiveScaffold.
we need simple CRUD most of
the time and we ActiveScaffold.
Most of our controllers are less than
70 lines and we seldom write forms.
We use the ActiveScaffold partial
forms almost every were sometimes
custpmizing them.
Clojure Web Frameworks are not
there yet.
We monitor the situation however
and will change our mind as soon
as it looks promiding...
Zack, keep the focus on the problem
to solve :)))
Luc P.
Sent from my iPod
Daniel Pritchett
Jul 11, 2010, 8:42:26 PM7/11/10
to Clojure
As a Clojure novice I'm happy to see the documentation side of the
Clojure ecosystem growing regardless of the stack used for a doc site.
Having a resource like a user-edited php.net will be a great help. I
am excited about submitting a few examples of my own.
On Jul 11, 9:14 am, Phil Hagelberg <p...@hagelb.org> wrote:
Phil Hagelberg
Jul 12, 2010, 2:43:03 PM7/12/10
to clo...@googlegroups.com
On Sun, Jul 11, 2010 at 4:10 PM, zkim <zacha...@gmail.com> wrote:
> If you're willing to continue the discussion, I'd like to keep this
> going (maybe another thread?). As I'm writing this I'm getting the
> feeling that I'm not quite articulating my thoughts well, and I think
> further discussion will help me to flesh them out.
> If you're willing to continue the discussion, I'd like to keep this
> going (maybe another thread?). As I'm writing this I'm getting the
> feeling that I'm not quite articulating my thoughts well, and I think
> further discussion will help me to flesh them out.
Actually I was hoping it would spark a discussion with the maintainers
and contributors of those projects. I haven't done any web development
myself in years, I just know it always bothers me to hear "It doesn't
work" or "It's not ready" about my own projects without more details.
-Phil
j-g-faustus
Jul 12, 2010, 6:25:35 PM7/12/10
to Clojure
The site looks very nice, I especially like the "find real world
examples" functionality and the fact that it collects documentation
for common non-core libraries as well.
I made my own cheat sheet for private use over the past month or so,
core functions only. It's at the 80% stage, I don't expect it will
ever be 100%, but I have found it useful:
http://faustus.webatu.com/clj-quick-ref.html
It is loosely inspired by the Ruby QuickRef
http://www.zenspider.com/Languages/Ruby/QuickRef.html
which I found tremendously useful.
The experience has told me that good documentation is a lot of work,
and I can see why people writing books want to get paid for their
efforts :)
So I appreciate the community aspect of your site. I expect that
managing a community is just as much (or more) of a challenge than the
technical aspects, but if you can get it working it can scale in a way
that no private effort can.
On Jul 11, 11:23 am, zkim <zachary....@gmail.com> wrote:
> > (3) +1 on making it very easy to see which version of an API
> > you are looking at. This should be both at the top level (some
> > way to say "show me 1.1") and on a per-var basis, reading
> > the :added metadata.
>
> This is something I'd like to discuss in-depth on the new google group
> (http://groups.google.com/group/clojuredocsorg). It is something that
> I'd really like to see, but I haven't worked through the
> implementation details in my head (multiple versions stored per var
> vs. diffs stored, UI around this, etc).
I would like to see this as well. In the short term I think the way
the official doc does it, just listing the "Since Clojure x.y"
metadata tag, works well enough.
I can't really see the benefit of listing the source code for the
function so prominently - in most cases I look up documentation to
find out how to use a function, not how to implement it. I would
suggest leaving it in a collapsed state initially.
I am missing some form of logical grouping, like "operations on
vectors".
Much of the benefit I get from using my own cheat sheet rather than
the official documentation is that I can zoom in on for example the
dozen or so operations that apply to agents (under "Concurrency" in my
cheat sheet) rather than wading through hundreds of names that may or
may not be relevant to what I am looking for.
All in all a great initiative, and I hope there will be room for some
level of grouping beyond "alphabetically" and "by namespace".
Regards
jf
examples" functionality and the fact that it collects documentation
for common non-core libraries as well.
I made my own cheat sheet for private use over the past month or so,
core functions only. It's at the 80% stage, I don't expect it will
ever be 100%, but I have found it useful:
http://faustus.webatu.com/clj-quick-ref.html
It is loosely inspired by the Ruby QuickRef
http://www.zenspider.com/Languages/Ruby/QuickRef.html
which I found tremendously useful.
The experience has told me that good documentation is a lot of work,
and I can see why people writing books want to get paid for their
efforts :)
So I appreciate the community aspect of your site. I expect that
managing a community is just as much (or more) of a challenge than the
technical aspects, but if you can get it working it can scale in a way
that no private effort can.
On Jul 11, 11:23 am, zkim <zachary....@gmail.com> wrote:
> > (3) +1 on making it very easy to see which version of an API
> > you are looking at. This should be both at the top level (some
> > way to say "show me 1.1") and on a per-var basis, reading
> > the :added metadata.
>
> This is something I'd like to discuss in-depth on the new google group
> (http://groups.google.com/group/clojuredocsorg). It is something that
> I'd really like to see, but I haven't worked through the
> implementation details in my head (multiple versions stored per var
> vs. diffs stored, UI around this, etc).
the official doc does it, just listing the "Since Clojure x.y"
metadata tag, works well enough.
I can't really see the benefit of listing the source code for the
function so prominently - in most cases I look up documentation to
find out how to use a function, not how to implement it. I would
suggest leaving it in a collapsed state initially.
I am missing some form of logical grouping, like "operations on
vectors".
Much of the benefit I get from using my own cheat sheet rather than
the official documentation is that I can zoom in on for example the
dozen or so operations that apply to agents (under "Concurrency" in my
cheat sheet) rather than wading through hundreds of names that may or
may not be relevant to what I am looking for.
All in all a great initiative, and I hope there will be room for some
level of grouping beyond "alphabetically" and "by namespace".
Regards
jf
j-g-faustus
Jul 12, 2010, 7:28:01 PM7/12/10
to Clojure
On Jul 13, 12:25 am, j-g-faustus <johannes.fries...@gmail.com> wrote:
> I made my own cheat sheet for private use over the past month or so,
> core functions only. It's at the 80% stage, I don't expect it will
> ever be 100%, but I have found it useful:
> http://faustus.webatu.com/clj-quick-ref.html
Looks like the hosting provider put my Clojure cheat sheet under
> I made my own cheat sheet for private use over the past month or so,
> core functions only. It's at the 80% stage, I don't expect it will
> ever be 100%, but I have found it useful:
> http://faustus.webatu.com/clj-quick-ref.html
review, I guess they found it suspicious... :)
According to their "website under review" page, it should be available
in a few hours.
If not, and if anyone is interested in seeing it, I can probably find
somewhere else to put it.
jf
j-g-faustus
Jul 13, 2010, 8:26:09 AM7/13/10
to Clojure
On 13 Jul, 01:28, j-g-faustus <johannes.fries...@gmail.com> wrote:
> On Jul 13, 12:25 am, j-g-faustus <johannes.fries...@gmail.com> wrote:
>
> > I made my own cheat sheet for private use over the past month or so,
> > core functions only. It's at the 80% stage, I don't expect it will
> > ever be 100%, but I have found it useful:
> > http://faustus.webatu.com/clj-quick-ref.html
>
> Looks like the hosting provider put my Clojure cheat sheet under
> review, I guess they found it suspicious... :)
It seems to have passed approval, so it is available again.
> On Jul 13, 12:25 am, j-g-faustus <johannes.fries...@gmail.com> wrote:
>
> > I made my own cheat sheet for private use over the past month or so,
> > core functions only. It's at the 80% stage, I don't expect it will
> > ever be 100%, but I have found it useful:
> > http://faustus.webatu.com/clj-quick-ref.html
>
> Looks like the hosting provider put my Clojure cheat sheet under
> review, I guess they found it suspicious... :)
In the context of this thread, the cheat sheet is primarily an
argument on how to best structure the information.
Personally I like the compact format of having categories, names,
description and examples all on the same page (to the extent that a 6k
line page can be called 'compact'), perhaps combined with links to
more extensive documentation.
YMMV, and I'm not sure if the format can be made to scale to the scope
and community nature of ClojureDocs.
But some form of categorization would be nice.
jf
Paul Moore
Jul 13, 2010, 2:37:49 PM7/13/10
to clo...@googlegroups.com
On 12 July 2010 23:25, j-g-faustus <johannes...@gmail.com> wrote:
> The site looks very nice, I especially like the "find real world
> examples" functionality and the fact that it collects documentation
> for common non-core libraries as well.
>
> I made my own cheat sheet for private use over the past month or so,
> core functions only. It's at the 80% stage, I don't expect it will
> ever be 100%, but I have found it useful:
> http://faustus.webatu.com/clj-quick-ref.html
> The site looks very nice, I especially like the "find real world
> examples" functionality and the fact that it collects documentation
> for common non-core libraries as well.
>
> I made my own cheat sheet for private use over the past month or so,
> core functions only. It's at the 80% stage, I don't expect it will
> ever be 100%, but I have found it useful:
> http://faustus.webatu.com/clj-quick-ref.html
Can I suggest omitting the "Table of contents" sidebar when printing?
I've not tried printing the document to see how it looks, but removing
the sidebar would be an essential starting point...
Paul.
.Bill Smith
Jul 13, 2010, 2:59:15 PM7/13/10
to Clojure
I agree. The in-code function documentation serves its purpose but
could be improved upon in a medium where space is at less of a
premium.
Bill Smith
Austin, TX
On Jul 10, 12:36 pm, James Reeves <jree...@weavejester.com> wrote:
could be improved upon in a medium where space is at less of a
premium.
Bill Smith
Austin, TX
On Jul 10, 12:36 pm, James Reeves <jree...@weavejester.com> wrote:
Meikel Brandmeyer
Jul 13, 2010, 4:04:24 PM7/13/10
to clo...@googlegroups.com
Hi,
Am 13.07.2010 um 14:26 schrieb j-g-faustus:
>>> I made my own cheat sheet for private use over the past month or so,
>>> core functions only. It's at the 80% stage, I don't expect it will
>>> ever be 100%, but I have found it useful:
>>> http://faustus.webatu.com/clj-quick-ref.html
Some comments after quickly skimming through:
next vs. rest: neither of those two „more“ idiomatic. They are just different. next will realise the next element of the sequence (of any), while rest will not. So in general you want rest, but sometimes next is useful, eg. in a loop: (loop [s (seq s)] (when s (do-something) (recur (next s))).
Your comment on sequence is wrong: sequence and seq are – like rest and next – two different things. It's not that sequence was the „old“ seq.
replicate is a relic from the time where repeat didn't have an optional n.
Your examples on transients are wrong. You have to capture the return value of the bang! functions as you would do with the non-bang versions. That (persistent! tm) works in your examples is an implementation detail.
condp has another form, which could be mentioned because it is not widely known:
user=> (condp some [1 2 3]
#{2 4 6} :>> inc
#{3 5 7} :>> dec)
3
recur recurs not only to the function, but also to the same arity. So (fn ([a] (println a)) ([a b] (recur (+ a b)))) does not work.
extends? does check whether (extend ...) was called on a protocol with the given type. This can be a Java class or something defined with with deftype/defrecord. However for the latter not when the protocol methods where specified inline.
io! is inside the transaction, but can be defined outside. (defn fn-with-io [] (io! (do-stuff))) ..... (dosync (fn-with-io)) <- exception
You might want to mention #_ in the comments section. It is a reader macro which drops the following read thing. Useful to comment out code without messing with the parens.
user=> [1 2 #_ 3]
[1 2]
In the require example: specifying :reload in an ns declaration smells.
You can also use :as with :use. (ns foo.bar (:use [frob.nicator :only (defflogistionreactor) :as frobber])). Can be useful at times.
I don't like your use of '(quote lists) everywhere. Please use vectors. They are the idiomatic answer of Clojure to quoted lists. Use quoted lists only where it is interesting to distinguish the list from the vector, eg. in (vec '(1 2 3)). (Related: if you find yourself quoting symbols, this means you should use backquote because your are writing a macro or you should actually use keywords.)
I really like your examples! They are simple, easy to understand, demonstrate edge cases and focus on the thing being demonstrated. Two thumbs up.
Hope that helps.
Sincerely
Meikel
PS: I'm apologise if some this seems to be nit-picking.
Rick Moynihan
Jul 13, 2010, 7:17:47 PM7/13/10
to clo...@googlegroups.com
On 11 July 2010 12:05, Lukasz Urbanek <res...@gmail.com> wrote:
> Looks very nice!
>
> Hoping for the categories to arrive to the core namespace. This really
> saves a lot of time for a clojure beginner like me.
> Looks very nice!
>
> Hoping for the categories to arrive to the core namespace. This really
> saves a lot of time for a clojure beginner like me.
+1
> Additionally, I'd prefer if the source was wasn't exposed by default
> (It's quite distracting when one is looking for the examples), some
> kind of "source" button that reveals it would be cool.
+1 - I agree with others that people should be encouraged to program
to the API, not the implementation. However sometimes its nice to be
able to see the nitty gritty, so having a reveal source link would be
great, without distracting from the more common case.
R.
j-g-faustus
Jul 13, 2010, 10:40:10 PM7/13/10
to Clojure
On Jul 13, 8:37 pm, Paul Moore <p.f.mo...@gmail.com> wrote:
> Can I suggest omitting the "Table of contents" sidebar when printing?
> I've not tried printing the document to see how it looks, but removing
> the sidebar would be an essential starting point...
Why would anyone want to print it?
> Can I suggest omitting the "Table of contents" sidebar when printing?
> I've not tried printing the document to see how it looks, but removing
> the sidebar would be an essential starting point...
I occasionally print longer texts like specifications, but for
reference material like Javadoc, ClojureDocs, the Ruby cheat sheet and
this page, I think HTML is a far superior format due to links and
browser search.
And 40+ loose single sheets is a rather cumbersome package unless you
have access to a book binder.
But if at least two people feel that they would really like to print
it out, I can skip the TOC on print.
(Making it look _nice_ on paper is a whole different ballgame, then
I'd have to look into pagination and page layouts, perhaps by
converting to DocBook or LaTex. That's outside the scope of what I
intended to do.)
On Jul 13, 10:04 pm, Meikel Brandmeyer <m...@kotka.de> wrote:
> Some comments after quickly skimming through:
> PS: I'm apologise if some this seems to be nit-picking.
Not at all, I'm still learning the language and happy to get the
details clarified.
The second form of condp and the #_ were omitted simply because I
didn't know about them, thanks for the heads-up.
For quoted lists, I take your point.
For the sequence operations examples it was somewhat deliberate, in
that a sequence is a very different datatype from a vector but pretty
much the same as a list.
I had a bug in some code that conj'ed elements onto a vector, but for
some reason it would switch direction in the middle and start adding
elements at the opposite end. It took me a while to figure out that it
was because concat'ing two vectors doesn't return a vector.
So I wanted to emphasize that using a sequence op on anything other
than a list is also a conversion from one datatype to another.
But I'll take another look, there may be better ways.
Thanks for your comments, much appreciated. I'll include them with the
next update.
Sincerely,
jf
Islon Scherer
Jul 16, 2010, 1:18:45 PM7/16/10
to Clojure
Hi.
Does clojuredocs expose any external API (json, xml... rest,
webservices, etc) so I can access the docs from my code?
Islon
On Jul 13, 11:40 pm, j-g-faustus <johannes.fries...@gmail.com> wrote:
> On Jul 13, 8:37 pm, Paul Moore <p.f.mo...@gmail.com> wrote:
>
> > Can I suggest omitting the "Table of contents" sidebar when printing?
> > I've not tried printing the document to see how it looks, but removing
> > the sidebar would be an essential starting point...
>
> Why would anyone want to print it?
>
> I occasionally print longer texts like specifications, but for
> reference material like Javadoc,ClojureDocs, the Ruby cheat sheet and
Does clojuredocs expose any external API (json, xml... rest,
webservices, etc) so I can access the docs from my code?
Islon
On Jul 13, 11:40 pm, j-g-faustus <johannes.fries...@gmail.com> wrote:
> On Jul 13, 8:37 pm, Paul Moore <p.f.mo...@gmail.com> wrote:
>
> > Can I suggest omitting the "Table of contents" sidebar when printing?
> > I've not tried printing the document to see how it looks, but removing
> > the sidebar would be an essential starting point...
>
> Why would anyone want to print it?
>
> I occasionally print longer texts like specifications, but for
Lee Hinman
Jul 16, 2010, 1:29:00 PM7/16/10
to clo...@googlegroups.com
Had another suggestion,
As an example contributor, It would be really nice to see a list of
functions that have no examples yet at a glance, so if I wanted to
work on adding examples I could go through a list and work on
functions that have no examples. I believe the clojure-examples
appspot wiki used to dim out functions that didn't have any examples
(I don't think it does this any more), which was very helpful.
If we did this, we could even have a percentage meter to work toward
100% API example coverage :)
- Lee
Daniel Werner
Jul 16, 2010, 6:50:26 PM7/16/10
to Clojure
Hi Zack,
I just take a quick look at your site and must say that I'm impressed.
This is going to become one of the utilities I constantly keep open in
the background while developing. Especially since features like the
Var cross-referencing tend to make easier to get the "big picture".
One thing I immediately wanted to do is browse the Enlive docs to
learn about the templating code, but couldn't simply search for
"Enlive" -- I had to either click the (less-visible) "All libraries"
link or search for a known Var like "defsnippet". A project search
feature, or a unified search that will search in Vars as well project
names, would be really helpful.
Thanks for investing your time into this site. May it prosper and
attract many prospective new Clojure developers :-)
-Daniel
I just take a quick look at your site and must say that I'm impressed.
This is going to become one of the utilities I constantly keep open in
the background while developing. Especially since features like the
Var cross-referencing tend to make easier to get the "big picture".
One thing I immediately wanted to do is browse the Enlive docs to
learn about the templating code, but couldn't simply search for
"Enlive" -- I had to either click the (less-visible) "All libraries"
link or search for a known Var like "defsnippet". A project search
feature, or a unified search that will search in Vars as well project
names, would be really helpful.
Thanks for investing your time into this site. May it prosper and
attract many prospective new Clojure developers :-)
-Daniel
Avram
Jul 16, 2010, 1:56:27 PM7/16/10
to Clojure
A few thoughts... It might be interesting to allow examples to be
rated. Quality or usefulness of the provided example could then be
inferred from the rating and highly rated examples could bubble to the
top or have the associated rating prominently shown.
~A
rated. Quality or usefulness of the provided example could then be
inferred from the rating and highly rated examples could bubble to the
top or have the associated rating prominently shown.
~A
zkim
Jul 17, 2010, 5:01:42 AM7/17/10
to Clojure
Islon- See the week 1 post on the CD.org group (http://
groups.google.com/group/clojuredocsorg/browse_thread/thread/
af7edbf85a6607c4) as to where this fits in on the timeline.
Lee- Very cool, I've added it to the UserVoice page.
Daniel- I agree, a great search experience is key for documentation
sites, see the week 1 post for more info.
Avram- I believe I missed addressing this in the week 1 post, thanks
for the reminder.
-Zack
groups.google.com/group/clojuredocsorg/browse_thread/thread/
af7edbf85a6607c4) as to where this fits in on the timeline.
Lee- Very cool, I've added it to the UserVoice page.
Daniel- I agree, a great search experience is key for documentation
sites, see the week 1 post for more info.
Avram- I believe I missed addressing this in the week 1 post, thanks
for the reminder.
-Zack
Reply all
Reply to author
Forward
0 new messages