Permalink
Browse files

Added a bunch of documentation. Added blank docstrings to vars that s…

…till need to be documented.
  • Loading branch information...
1 parent 16d32e0 commit 689a2bf4905fb4f6e48e2267d6fb935233ccbdb8 Dave Moore committed Nov 23, 2011
View
1 .gitignore
@@ -6,4 +6,5 @@ classes/
.lein-deps-sum
*.iml
.idea
+*.DS_Store
View
2 joodo/project.clj
@@ -1,4 +1,4 @@
-(defproject joodo "0.6.1-SNAPSHOT"
+(defproject joodo "0.6.2-SNAPSHOT"
:description "Joodo, a Clojure framework for web apps."
:license {:name "The MIT License"
:url "file://LICENSE"
View
3 joodo/src/joodo/controllers.clj
@@ -1,4 +1,5 @@
-(ns joodo.controllers
+(ns ^{:doc "This namespace contains functions that creates a ring-handler and dynamically loads controllers"}
+ joodo.controllers
(:use
[compojure.core :only (routing)])
(:require
View
60 joodo/src/joodo/datetime.clj
@@ -1,4 +1,5 @@
-(ns joodo.datetime
+(ns ^{:doc "This namespace holds functions that make dealing with dates and times easy."}
+ joodo.datetime
(:import
[java.util Date Calendar GregorianCalendar]
[java.text SimpleDateFormat]))
@@ -10,6 +11,10 @@
(Date.))
(defn datetime
+ "Returns a Java Date Object with the specified arguments. Expects one of the following for arguments:
+ 1. year month day
+ 2. year month day hour minute
+ 3. year month day hour minute second"
([year month day] (.getTime (GregorianCalendar. year (dec month) day)))
([year month day hour minute] (.getTime (GregorianCalendar. year (dec month) day hour minute)))
([year month day hour minute second] (.getTime (GregorianCalendar. year (dec month) day hour minute second))))
@@ -36,33 +41,60 @@
(after? date start)
(before? date end)))
-(defn seconds [n] (* n 1000))
-(defn minutes [n] (* n 60000))
-(defn hours [n] (* n 3600000))
-(defn days [n] (* n 86400000))
-(defn months [n] [Calendar/MONTH n])
-(defn years [n] [Calendar/YEAR n])
+(defn seconds
+ "Converts seconds to milliseconds"
+ [n] (* n 1000))
-(defn to-calendar [datetime]
+(defn minutes
+ "Converts minutes to milliseconds"
+ [n] (* n 60000))
+
+(defn hours
+ "Converts hours to milliseconds"
+ [n] (* n 3600000))
+
+(defn days
+ "Converts days to milliseconds"
+ [n] (* n 86400000))
+
+(defn months
+ ""
+ [n] [Calendar/MONTH n])
+
+(defn years
+ ""
+ [n] [Calendar/YEAR n])
+
+(defn to-calendar
+ ""
+ [datetime]
(doto (GregorianCalendar.)
(.setTime datetime)))
-(defn- mod-time-by-units [time [unit n] direction]
+(defn- mod-time-by-units
+ ""
+ [time [unit n] direction]
(let [calendar (GregorianCalendar.)
n (direction n)]
(.setTime calendar time)
(.add calendar unit n)
(.getTime calendar)))
-(defn- mod-time [time bit direction]
+(defn- mod-time
+ ""
+ [time bit direction]
(cond
(number? bit) (Date. (direction (.getTime time) bit))
(vector? bit) (mod-time-by-units time bit direction)))
-(defn before [^Date time & bits]
+(defn before
+ ""
+ [^Date time & bits]
(reduce #(mod-time %1 %2 -) time bits))
-(defn after [^Date time & bits]
+(defn after
+ ""
+ [^Date time & bits]
(reduce #(mod-time %1 %2 +) time bits))
(defn seconds-ago
@@ -151,7 +183,9 @@
(= SimpleDateFormat (class format)) format
:else (throw (Exception. (str "Unhandled date format: " format)))))
-(defn parse-datetime [format value]
+(defn parse-datetime
+ ""
+ [format value]
(let [formatter (to-date-formater format)]
(.parse formatter value)))
View
9 joodo/src/joodo/env.clj
@@ -1,8 +1,11 @@
-(ns joodo.env)
+(ns ^{:doc "This namespace holds functions that read the current environment that the application is in (according to the system properties)."}
+ joodo.env)
-(def *env* (atom {:joodo-env (or (System/getProperty "joodo.env") "development")}))
+(def ^{:doc "Holds information about the current environment. That data can be
+ retrieved with the following syntax: (get @*env* :joodo-env)"}
+ *env* (atom {:joodo-env (or (System/getProperty "joodo.env") "development")}))
-(defn env [key]
+(defn ^{:doc "Gets information about the current environment"} env [key]
(or
(get @*env* (keyword key))
(get @*env* (str key))
View
3 joodo/src/joodo/middleware/flash.clj
@@ -1,4 +1,5 @@
-(ns joodo.middleware.flash)
+(ns ^{:doc "This namespace contains functions that deal with flash messages."}
+ joodo.middleware.flash)
(defn- read-flash [request]
(let [session (:session request)
View
3 joodo/src/joodo/middleware/keyword_cookies.clj
@@ -1,4 +1,5 @@
-(ns joodo.middleware.keyword-cookies)
+(ns ^{:doc "This namespace deals with cookie information."}
+ joodo.middleware.keyword-cookies)
(defn- keyify [target]
(cond
View
3 joodo/src/joodo/middleware/multipart_params.clj
@@ -1,4 +1,5 @@
-(ns joodo.middleware.multipart-params
+(ns ^{:doc "This namespace deals with multipart parameters."}
+ joodo.middleware.multipart-params
(:import [org.apache.commons.fileupload.servlet ServletFileUpload]
[org.apache.commons.fileupload.util Streams]
org.apache.commons.io.IOUtils))
View
7 joodo/src/joodo/middleware/refresh.clj
@@ -1,4 +1,5 @@
-(ns joodo.middleware.refresh
+(ns ^{:doc "This namespace contains functions that interface with the fresh library. The fresh library automatically loads up files that have recently been changed."}
+ joodo.middleware.refresh
(:use
[fresh.core :only (freshener ns-to-file)]))
@@ -24,7 +25,9 @@
(catch Exception e
(println "ON NO!!! Can't clear controller cache." e))))
-(defn wrap-refresh [handler]
+(defn wrap-refresh
+ "When integrated with the current ring handler, this function reloads newly saved files (such as controllers) while in development mode."
+ [handler]
(let [refresh! (freshener files-to-keep-fresh report-refresh)]
(fn [request]
(refresh!)
View
6 joodo/src/joodo/middleware/request.clj
@@ -1,6 +1,8 @@
-(ns joodo.middleware.request)
+(ns ^{:doc "This namespace contains logic that stores information about the current HTTP request."}
+ joodo.middleware.request)
-(def *request* {})
+(def ^{:doc ""}
+ *request* {})
(defn wrap-bind-request
"Makes the *request* var available and sets
View
3 joodo/src/joodo/middleware/servlet_session.clj
@@ -1,4 +1,5 @@
-(ns joodo.middleware.servlet-session)
+(ns ^{:doc "This namespace holds functions that keep track of session information."}
+ joodo.middleware.servlet-session)
(defprotocol SessionContainer
(entry-keys [this])
View
10 joodo/src/joodo/middleware/verbose.clj
@@ -1,10 +1,14 @@
-(ns joodo.middleware.verbose
+(ns ^{:doc "This namespace contains functions that output the current state of the server."}
+ joodo.middleware.verbose
(:use
[joodo.util.pretty-map :only (pretty-map)]))
-(def request-count (atom 0))
+(def ^{:doc ""}
+ request-count (atom 0))
-(defn wrap-verbose [handler]
+(defn wrap-verbose
+ "Outputs the state of the server to standard output as requests are getting made."
+ [handler]
(fn [request]
(let [request-id (swap! request-count inc)]
(println "REQUEST " request-id " ========================================================================================")
View
7 joodo/src/joodo/middleware/view_context.clj
@@ -1,4 +1,5 @@
-(ns joodo.middleware.view-context
+(ns ^{:doc "This namespace contains logic that incorporates a var called *view-context* with the ring-handler."}
+ joodo.middleware.view-context
(:use
[joodo.views :only (*view-context*)]))
@@ -13,6 +14,4 @@
view-context (merge *view-context* options)]
(fn [request]
(binding [*view-context* view-context]
- (handler request)))))
-
-
+ (handler request)))))
View
17 joodo/src/joodo/spec_helpers/controller.clj
@@ -1,11 +1,13 @@
-(ns joodo.spec-helpers.controller
+(ns ^{:doc "This namespace is comprised of functions that work with the Speclj testing framework to make testing controller logic easy."}
+ joodo.spec-helpers.controller
(:use
[speclj.core]
[joodo.views :only (*view-context* render-template render-html)]
[joodo.datetime :only (minutes-from-now)]
[joodo.middleware.request :only (*request*)]))
-(declare *routes*)
+(declare ^{:doc ""}
+ *routes*)
(defn with-routes
"Binds the supplied routes to the *routes* var so that tests can use those
@@ -37,9 +39,14 @@
[resource & extras]
(apply request :post resource extras))
-(def rendered-template (atom nil))
-(def rendered-html (atom nil))
-(def rendered-context (atom nil))
+(def ^{:doc ""}
+ rendered-template (atom nil))
+
+(def ^{:doc ""}
+ rendered-html (atom nil))
+
+(def ^{:doc ""}
+ rendered-context (atom nil))
(defn mock-render-template
"Sets rendered-template to the template provided in the first arguement
View
23 joodo/src/joodo/spec_helpers/datastore.clj
@@ -1,23 +0,0 @@
-(ns joodo.spec-helpers.datastore
- (:use
- [speclj.core])
- (:import
- [com.google.appengine.tools.development.testing
- LocalServiceTestConfig
- LocalDatastoreServiceTestConfig
- LocalBlobstoreServiceTestConfig
- LocalServiceTestHelper]
- [com.google.apphosting.api ApiProxy]))
-
-(defn tear-down []
- (.stop (ApiProxy/getDelegate))
- (ApiProxy/clearEnvironmentForCurrentThread)
- )
-
-(defn with-local-datastore []
- (around [it]
- (try
- (.setUp (LocalServiceTestHelper.
- (into-array LocalServiceTestConfig [(LocalBlobstoreServiceTestConfig.) (LocalDatastoreServiceTestConfig.)])))
- (it)
- (finally (tear-down)))))
View
24 joodo/src/joodo/spec_helpers/mail.clj
@@ -1,24 +0,0 @@
-(ns joodo.spec-helpers.mail
- (:use
- [speclj.core]
- [joodo.mail])
- (:import
- [com.google.appengine.api.mail MailService]))
-
-(deftype FakeMailService [sends sends-to-admins]
- MailService
- (send [this message] (swap! sends conj (message->map message)))
- (sendToAdmins [this message] (swap! sends-to-admins conj (message->map message))))
-
-(def fake-mail-service (atom nil))
-
-(defn with-fake-mail []
- (before
- (reset! fake-mail-service (FakeMailService. (atom []) (atom [])))
- (reset! mail-service-instance @fake-mail-service)))
-
-(defn sent-messages []
- @(.sends @fake-mail-service))
-
-(defn sent-messages-to-admins []
- @(.sends-to-admins @fake-mail-service))
View
42 joodo/src/joodo/spec_helpers/users.clj
@@ -1,42 +0,0 @@
-(ns joodo.spec-helpers.users
- (:use
- [speclj.core :only (before)]
- [joodo.users])
- (:import
- [com.google.appengine.api.users UserService]))
-
-(deftype FakeUserService [user admin? logged-in?]
- UserService
- (createLoginURL [this destination-url]
- (format "http://log.in?destination=%s" destination-url))
- (createLoginURL [this destination-url auth-domain]
- (format "http://log.in?destination=%s&authDomain=%s" destination-url auth-domain))
- (createLoginURL [this destination-url auth-domain federated-identity attributes-request]
- (format "http://log.in?destination=%s&authDomain=%s&federatedIdentity=%s&attributes=%s" destination-url auth-domain federated-identity attributes-request))
- (createLogoutURL [this destination-url]
- (format "http://log.out?destination=%s" destination-url))
- (createLogoutURL [this destination-url auth-domain]
- (format "http://log.out?destination=%s&authDomain=%s" destination-url auth-domain))
- (getCurrentUser [this] @user)
- (isUserAdmin [this] @admin?)
- (isUserLoggedIn [this] @logged-in?))
-
-(def default-user-values {:name "Test User"
- :email "test@user.com"
- :auth-domain "test.com"
- :user-id "1234567890"})
-
-(def fake-user-service (atom nil))
-
-(defn setup-fake-user [& args]
- (let [values (apply hash-map args)
- service @fake-user-service]
- (when (contains? values :user) (reset! (.user service) (map->user (merge default-user-values (:user values)))))
- (when (contains? values :admin?) (reset! (.admin? service) (:admin? values)))
- (when (contains? values :logged-in?) (reset! (.logged-in? service) (:logged-in? values)))))
-
-(defn with-fake-users [& args]
- (before
- (reset! fake-user-service (FakeUserService. (atom nil) (atom false) (atom false)))
- (apply setup-fake-user args)
- (reset! user-service-instance @fake-user-service)))
View
15 joodo/src/joodo/spec_helpers/view.clj
@@ -1,4 +1,5 @@
-(ns joodo.spec-helpers.view
+(ns ^{:doc "This namespace is comprised of functions that work with the Speclj testing framework to make testing view logic easy."}
+ joodo.spec-helpers.view
(:use
[speclj.core :only (around)]
[clojure.xml :only (parse)]
@@ -35,13 +36,19 @@
node
(find-tag* (filter map? (:content node)) matcher)))
-(defn rendered-content [content]
+(defn rendered-content
+ ""
+ [content]
(parse (java.io.ByteArrayInputStream. (.getBytes content))))
-(defn rendered-html [template & kwargs]
+(defn rendered-html
+ ""
+ [template & kwargs]
(rendered-content (apply render-html template kwargs)))
-(defn rendered-hiccup [template & kwargs]
+(defn rendered-hiccup
+ ""
+ [template & kwargs]
(rendered-content (apply render-hiccup template kwargs)))
(defn rendered-template
View
3 joodo/src/joodo/string.clj
@@ -1,4 +1,5 @@
-(ns joodo.string)
+(ns ^{:doc "This namespace contains functions that are useful when dealing with strings."}
+ joodo.string)
(defn gsub
"Matches patterns and replaces those matches with a specified value.
View
11 joodo/src/joodo/views.clj
@@ -1,8 +1,10 @@
-(ns joodo.views
+(ns ^{:doc "This namespace contains functions that are used to display the view files."}
+ joodo.views
(:use
[hiccup.core]))
-(def *view-context* {
+(def ^{:doc "Var that holds a map with all the information required to render a page."}
+ *view-context* {
:template-root "view"
:layout "layout"
:ns `joodo.kake.default-rendering
@@ -52,7 +54,10 @@
(binding [*view-context* (updated-context kwargs)]
(render-in-layout hiccup-src)))
-(def render-html render-hiccup)
+(def ^{:doc "Expects html or hiccup data and any optional parameters. Transforms
+ any hiccup data provided and renders html into the default layout. If a layout is
+ supplied in one of the optional parameters, it will render in the specified layout."}
+ render-html render-hiccup)
(defn render-template
"Expects the location of a template and any optional parameters. Returns the

0 comments on commit 689a2bf

Please sign in to comment.