--
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
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
Questions / thoughts?
-Zack
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)
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
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
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
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
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 P.
Sent from my iPod
Could you provide details about what it was specifically that you
found was lacking?
-Phil
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
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
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
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.
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.
+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.
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