Fix typos and clarity issues in doc-strings

Author: John Berry

src/compojure/api/common.clj

@@ -2,7 +2,8 @@
   (:require [org.tobereplaced.lettercase :as lc]))
 
 (defn path-vals
-  "Returns vector of tuples containing path vector to the value and the value."
+  "Returns vector of tuples each containing the path vector to the 
+   value in the first position, and the value in the second position."
   [m]
   (letfn
     [(pvals [l p m]
@@ -15,7 +16,7 @@
     (pvals [] [] m)))
 
 (defn assoc-in-path-vals
-  "Re-created a map from it's path-vals extracted with (path-vals)."
+  "Re-creates a map from its path-vals extracted with (path-vals)."
   [c] (reduce (partial apply assoc-in) {} c))
 
 (defmacro re-resolve
@@ -34,7 +35,7 @@
 (defn eval-re-resolve [x] (eval `(re-resolve ~x)))
 
 (defn assoc-map-ordered
-  "assocs a value into a map forcing the implementation to be
+  "assocs a value into a map, forcing the implementation to be
    clojure.lang.PersistentArrayMap instead of clojure.lang.PersistentHashMap,
    thus retaining the insertion order. O(n)."
   [m k v] (apply array-map (into (vec (apply concat m)) [k v])))

src/compojure/api/core.clj

@@ -62,8 +62,8 @@
   optionally be followed by a doc-string and metadata map. Generates an
   extra private Var with `_` + name to the given namespace holding the
   actual routes, caller doesn't have to care about this. Accessing defroutes*
-  over Var add tiny run-time penalty, but allows massive better development
-  speed as the defroutes* can be compiled seperately."
+  over Var adds a tiny run-time penalty, but allows massively improved 
+  development speed as the defroutes* can be compiled seperately."
   [name & routes]
   (let [source (drop 2 &form)
         [name routes] (name-with-attributes name routes)

src/compojure/api/meta.clj

@@ -126,7 +126,7 @@
     (throw
       (IllegalArgumentException.
         (str
-          "You are using old format with :responses. Since Compojure-api 0.21.0, "
+          "You are using an old format with :responses. Since Compojure-api 0.21.0, "
           "plain ring-swagger 2.0 models are used. Example:\n\n"
           ":responses {400 nil}\n"
           ":responses {400 {:schema ErrorSchema}}\n"
@@ -193,7 +193,7 @@
 (defmethod restructure-param :tags [_ tags acc]
   (update-in acc [:parameters :tags] (comp set into) tags))
 
-; Defines a return type and coerced the return value of a body against it.
+; Defines a return type and coerces the return value of a body against it.
 ; Examples:
 ; :return MySchema
 ; :return {:value String}

src/compojure/api/middleware.clj

@@ -47,7 +47,7 @@
       (error-handler error))))
 
 (defn wrap-exceptions
-  "Catches all exceptions and delegates to right error handler accoring to :type of Exceptions
+  "Catches all exceptions and delegates to correct error handler according to :type of Exceptions
    - **:handlers** - a map from exception type to handler
      - **:compojure.api.exception/default** - Handler used when exception type doesn't match other handler,
                                               by default prints stack trace."
@@ -148,7 +148,7 @@
     (throw+ e)))
 
 (defn serializable?
-  "Predicate which return true if the response body is serializable.
+  "Predicate which returns true if the response body is serializable.
    That is, return type is set by :return compojure-api key or it's
    a collection."
   [_ {:keys [body] :as response}]
@@ -186,7 +186,7 @@
 
                                       Note: To catch Schema errors use {:schema.core/error compojure.api.exception/schema-error-handler}
 
-                                      Note: Adding alias for exception namespace makes it easier to define these options.
+                                      Note: Adding an alias for exception namespace makes it easier to define these options.
 
    - **:format**                    for ring-middleware-format middlewares
        - **:formats**                 sequence of supported formats, e.g. `[:json-kw :edn]`
@@ -199,7 +199,7 @@
                                     e.g. `{:ignore-missing-mappings? true}`
 
    - **:coercion**                  A function from request->type->coercion-matcher, used
-                                    in enpoint coersion for :json, :query and :response.
+                                    in endpoint coercion for :json, :query and :response.
                                     Defaults to `compojure.api.middleware/default-coercion-matchers`
 
    - **:components**                Components which should be accessible to handlers using

src/compojure/api/swagger.clj

@@ -339,7 +339,7 @@
   (boolean (swagger-spec-path api)))
 
 (defn validate
-  "Validates a api. If the api is Swagger-enabled, the swagger-docs
+  "Validates an api. If the api is Swagger-enabled, the swagger-docs
   endpoint is requested. Returns either the (valid) api or throws an
   exception."
   [api]

test/compojure/api/coercion_test.clj

@@ -22,15 +22,15 @@
                     ping-route)]
           (get* app "/ping") => (fails-with 500)))
 
-      (fact "response-coersion can ba disabled"
+      (fact "response-coercion can be disabled"
         (let [app (api
                     {:coercion mw/no-response-coercion}
                     ping-route)]
           (let [[status body] (get* app "/ping")]
             status => 200
             body => {:pong 123})))))
 
-  (fact "body coersion"
+  (fact "body coercion"
     (let [beer-route (POST* "/beer" []
                        :body [body {:beers #{(s/enum "ipa" "apa")}}]
                        (ok body))]
@@ -42,7 +42,7 @@
             status => 200
             body => {:beers ["ipa" "apa"]})))
 
-      (fact "body-coersion can ba disabled"
+      (fact "body-coercion can be disabled"
         (let [no-body-coercion (constantly (dissoc mw/default-coercion-matchers :body))
               app (api
                     {:coercion no-body-coercion}
@@ -51,14 +51,14 @@
             status => 200
             body => {:beers ["ipa" "apa" "ipa"]})))
 
-      (fact "body-coersion can ba changed"
+      (fact "body-coercion can be changed"
         (let [nop-body-coercion (constantly (assoc mw/default-coercion-matchers :body (constantly nil)))
               app (api
                     {:coercion nop-body-coercion}
                     beer-route)]
           (post* app "/beer" (json {:beers ["ipa" "apa" "ipa"]})) => (fails-with 400)))))
 
-  (fact "query coersion"
+  (fact "query coercion"
     (let [query-route (GET* "/query" []
                         :query-params [i :- s/Int]
                         (ok {:i i}))]
@@ -70,7 +70,7 @@
             status => 200
             body => {:i 10})))
 
-      (fact "query-coersion can ba disabled"
+      (fact "query-coercion can be disabled"
         (let [no-query-coercion (constantly (dissoc mw/default-coercion-matchers :string))
               app (api
                     {:coercion no-query-coercion}
@@ -79,14 +79,14 @@
             status => 200
             body => {:i "10"})))
 
-      (fact "query-coersion can ba changed"
+      (fact "query-coercion can be changed"
         (let [nop-query-coercion (constantly (assoc mw/default-coercion-matchers :string (constantly nil)))
               app (api
                     {:coercion nop-query-coercion}
                     query-route)]
           (get* app "/query" {:i 10}) => (fails-with 400)))))
 
-  (fact "route-spesific coercion"
+  (fact "route-specific coercion"
     (let [app (api
                 (GET* "/default" []
                   :query-params [i :- s/Int]

test/compojure/api/swagger_test.clj

@@ -82,7 +82,7 @@
 
 
 (fact "->swagger2info"
-  (fact "old format get's converted to new with warnings"
+  (fact "old format gets converted to new with warnings"
     (binding [*out* (StringWriter.)]
       (select-swagger2-parameters
         {:version ..version..