-
Notifications
You must be signed in to change notification settings - Fork 77
Examples Guidelines Draft
##Purpose The example sections on each var page are there to provide simple, isolated examples of var usage.
##General In the interest of keeping things compact, yet readable please pay attention to whitespace.
Comments should directly precede the code block which they describe, don't put a line break.
Comments should be of the ';;' variety, not ';', with a space before the start of text.
Lines to be executed should start with either user=>, or user>, which will help with automatic verification.
Comments are not required for very simple examples.
Leave one line of whitespace after output from the repl.
Good: user=> (println "foo") foo
user=> (println "bar")
bar
user=> (println "baz")
baz
Bad: user=> (println "foo") foo user=> (println "bar") bar user=> (println "baz") baz
##Complexity Examples should be as stand-alone as possible, and you should assume the reader is coming from a programming background, with little to no Clojure experience.
If the target var is not part of the core ns (or otherwise not 'use'd by the repl by default) please include the use / require statement. (Should we nix this as well, the ns is at the top of the page anyway? pros: make examples more readable / shorter, cons: lots of questions about not found errors)
Each example should be either broad, or deep, not both. For example, the following example for not= shows the broad range of inputs allowed. (need to find a var that has both broad and deep examples)
Broad: user=> (not= 1 1) false
user=> (not= 1 2)
true
user=> (not= true true)
false
user=> (not= true false)
true
user=> (not= true true true true)
false
user=> (not= true true false true)
true
Deep: ;; A future is calculated in another thread user=> (def f (future (Thread/sleep 10000) 100)) #'user/f
;; When you dereference it you will block until the result is available.
user=> @f
100
;; Dereferencing again will return the already calculated value immediately.
user=> @f
100
Gotchas??