Change docstrings to markdown format

project.clj

@@ -12,6 +12,7 @@
   :plugins [[lein-codox "0.9.3"]]
   :codox
   {:output-path "codox"
+   :metadata {:doc/format :markdown}
    :source-uri "http://github.com/weavejester/compojure/blob/{version}/{filepath}#L{line}"}
   :profiles
   {:dev {:jvm-opts ^:replace []

src/compojure/coercions.clj

@@ -2,7 +2,7 @@
   "Functions for coercing route parameters into different types.")
 
 (defn as-int
-  "Parse a string into an integer, or nil if the string cannot be parsed."
+  "Parse a string into an integer, or `nil` if the string cannot be parsed."
   [s]
   (try
     (Long/parseLong s)
@@ -12,7 +12,7 @@
   #"[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}")
 
 (defn as-uuid
-  "Parse a string into a UUID, or nil if the string cannot be parsed."
+  "Parse a string into a UUID, or `nil` if the string cannot be parsed."
   [s]
   (if (re-matches uuid-pattern s)
     (try

src/compojure/core.clj

@@ -2,7 +2,7 @@
   "A DSL for building Ring handlers from smaller routes.
 
   Compojure routes are semantically the same as Ring handlers, with the
-  exception that routes may return nil to indicate they do not match.
+  exception that routes may return `nil` to indicate they do not match.
 
   This namespace provides functions and macros for concisely constructing
   routes and combining them together to form more complex functions."
@@ -137,7 +137,7 @@
             (wrap-route-info route-info))))))
 
 (defn compile-route
-  "Compile a route in the form (method path bindings & body) into a function.
+  "Compile a route in the form `(method path bindings & body)` into a function.
   Used to create custom route macros."
   [method path bindings body]
   `(make-route
@@ -162,31 +162,31 @@
   (let [[name routes] (macro/name-with-attributes name routes)]
    `(def ~name (routes ~@routes))))
 
-(defmacro GET "Generate a GET route."
+(defmacro GET "Generate a `GET` route."
   [path args & body]
   (compile-route :get path args body))
 
-(defmacro POST "Generate a POST route."
+(defmacro POST "Generate a `POST` route."
   [path args & body]
   (compile-route :post path args body))
 
-(defmacro PUT "Generate a PUT route."
+(defmacro PUT "Generate a `PUT` route."
   [path args & body]
   (compile-route :put path args body))
 
-(defmacro DELETE "Generate a DELETE route."
+(defmacro DELETE "Generate a `DELETE` route."
   [path args & body]
   (compile-route :delete path args body))
 
-(defmacro HEAD "Generate a HEAD route."
+(defmacro HEAD "Generate a `HEAD` route."
   [path args & body]
   (compile-route :head path args body))
 
-(defmacro OPTIONS "Generate an OPTIONS route."
+(defmacro OPTIONS "Generate an `OPTIONS` route."
   [path args & body]
   (compile-route :options path args body))
 
-(defmacro PATCH "Generate a PATCH route."
+(defmacro PATCH "Generate a `PATCH` route."
   [path args & body]
   (compile-route :patch path args body))
 
@@ -243,9 +243,9 @@
   The following example demonstrates defining two routes with a common
   path prefix ('/user/:id') and a common binding ('id'):
 
-    (context \"/user/:id\" [id]
-      (GET \"/profile\" [] ...)
-      (GET \"/settings\" [] ...))"
+      (context \"/user/:id\" [id]
+        (GET \"/profile\" [] ...)
+        (GET \"/settings\" [] ...))"
   [path args & routes]
   `(#'if-context
     ~(context-route path)
@@ -254,8 +254,11 @@
         (routing request# ~@routes)))))
 
 (defmacro let-routes
-  "Takes a vector of bindings and a body of routes. Equivalent to:
-  (let [...] (routes ...))"
+  "Takes a vector of bindings and a body of routes.
+
+  Equivalent to:
+
+      (let [...] (routes ...))"
   [bindings & body]
   `(let ~bindings (routes ~@body)))
 

src/compojure/handler.clj

@@ -1,7 +1,10 @@
 (ns compojure.handler
   "Functions to create Ring handlers from routes.
 
-  This namespace has been DEPRECATED in favor of the ring-defaults library."
+  This namespace has been **DEPRECATED** in favor of the [ring-defaults][]
+  library.
+
+  [ring-defaults]: https://github.com/ring-clojure/ring-defaults"
   {:deprecated "1.2"}
   (:use [ring.middleware params
                          keyword-params
@@ -19,9 +22,10 @@
 (defn api
   "Create a handler suitable for a web API. This adds the following
   middleware to your routes:
-    - wrap-params
-    - wrap-nested-params
-    - wrap-keyword-params"
+
+  - wrap-params
+  - wrap-nested-params
+  - wrap-keyword-params"
   {:deprecated "1.2"}
   [routes]
   (-> routes
@@ -32,18 +36,24 @@
 (defn site
   "Create a handler suitable for a standard website. This adds the
   following middleware to your routes:
-    - wrap-session
-    - wrap-flash
-    - wrap-cookies
-    - wrap-multipart-params
-    - wrap-params
-    - wrap-nested-params
-    - wrap-keyword-params
+
+  - wrap-session
+  - wrap-flash
+  - wrap-cookies
+  - wrap-multipart-params
+  - wrap-params
+  - wrap-nested-params
+  - wrap-keyword-params
 
   A map of options may also be provided. These keys are provided:
-    :session   - a map of session middleware options
-    :multipart - a map of multipart-params middleware options"
-  {:deprecated "1.2"}
+
+  :session
+  : a map of session middleware options
+
+  :multipart
+  : a map of multipart-params middleware options"
+  {:deprecated "1.2"
+   :arglists '([routes] [routes options])}
   [routes & [opts]]
   (-> (api routes)
       (with-opts wrap-multipart-params (:multipart opts))

src/compojure/middleware.clj

@@ -1,4 +1,5 @@
 (ns compojure.middleware
+  "Optional middleware to enhance routing in Compojure."
   (:require [compojure.core :refer [wrap-routes]]
             [ring.util.response :as resp]))
 
@@ -13,10 +14,10 @@
   (resp/redirect (:compojure/path request) 301))
 
 (defn wrap-canonical-redirect
-  "Middleware that permanently redirects any non-canonical route to its canonical
-  equivalent, based on a make-canonical function that changes a URI string into
-  its canonical form. If not supplied, make-canonical function will default to
-  remove-trailing-slash."
+  "Middleware that permanently redirects any non-canonical route to its
+  canonical equivalent, based on a make-canonical function that changes a URI
+  string into its canonical form. If not supplied, the make-canonical function
+  will default to [[remove-trailing-slash]]."
   ([handler]
    (wrap-canonical-redirect handler remove-trailing-slash))
   ([handler make-canonical]

src/compojure/response.clj

@@ -5,7 +5,7 @@
 
 (defprotocol Renderable
   "A protocol that tells Compojure how to handle the return value of routes
-  defined by GET, POST, etc.
+  defined by [[GET]], [[POST]], etc.
 
   This protocol supports rendering strings, maps, functions, refs, files, seqs,
   input streams and URLs by default, and may be extended to cover many custom

src/compojure/route.clj

@@ -1,5 +1,5 @@
 (ns compojure.route
-  "Route functions that define common behavior."
+  "Functions for defining common types of routes."
   (:require [compojure.response :as response]
             [compojure.core :refer [GET rfn]]
             [ring.util.mime-type :as mime]
@@ -15,31 +15,46 @@
     response))
 
 (defn files
-  "A route for serving static files from a directory. Accepts the following
-  keys:
-    :root       - the root path where the files are stored, defaults to 'public'
-    :mime-types - an optional map of file extensions to mime types"
-  [path & [options]]
-  (GET (add-wildcard path) {{file-path :*} :route-params}
-    (let [options  (merge {:root "public"} options)
-          response (file-response file-path options)]
-      (if response
-        (add-mime-type response (str (:body response)) options)))))
+  "Returns a route for serving static files from a directory.
+
+  Accepts the following options:
+
+  :root
+  : the root path where the files are stored, defaults to \"public\"
+
+  :mime-types
+  : an optional map of file extensions to mime types"
+  ([path]
+   (files path {}))
+  ([path options]
+   (GET (add-wildcard path) {{file-path :*} :route-params}
+     (let [options  (merge {:root "public"} options)
+           response (file-response file-path options)]
+       (if response
+         (add-mime-type response (str (:body response)) options))))))
 
 (defn resources
-  "A route for serving resources on the classpath. Accepts the following
-  keys:
-    :root       - the root prefix path of the resources, defaults to 'public'
-    :mime-types - an optional map of file extensions to mime types"
-  [path & [options]]
-  (GET (add-wildcard path) {{resource-path :*} :route-params}
-    (let [root (:root options "public")]
-      (some-> (resource-response (str root "/" resource-path))
-              (add-mime-type resource-path options)))))
+  "Returns a route for serving resources on the classpath.
+
+  Accepts the following options:
+
+  :root
+  : the root prefix path of the resources, defaults to \"public\"
+
+  :mime-types
+  : an optional map of file extensions to mime types"
+  ([path]
+   (resources path {}))
+  ([path options]
+   (GET (add-wildcard path) {{resource-path :*} :route-params}
+     (let [root (:root options "public")]
+       (some-> (resource-response (str root "/" resource-path))
+               (add-mime-type resource-path options))))))
 
 (defn not-found
-  "A route that returns a 404 not found response, with its argument as the
-  response body."
+  "Returns a route that always returns a 404 \"Not Found\" response with the
+  supplied response body. The response body may be anything accepted by the
+  [[response/render]] function."
   [body]
   (fn [request]
     (-> (response/render body request)