Examples Guidelines Draft

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

##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: (not= 1 1) ; => false

(not= 1 2)
; => true

(not= true true)
; => false

(not= true false)
; => true

(not= true true true true)
; => false

(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??

Indentation

Linking