                :param-types (.getParameterTypes m)
                :is-static (java.lang.reflect.Modifier/isStatic (.getModifiers m))}))))
 
-(defn hint-param [param type]
+(defn- hint-symbol
+  "Hints the provided symbol using the provided type.
+  For primitive types uses the Java wrapper classes."
+  [sym type]
   (let [boxed-primitive {"int" java.lang.Integer "long" java.lang.Long
                          "short" java.lang.Short "float" java.lang.Float
                          "double" java.lang.Double "boolean" java.lang.Boolean
                          "byte" java.lang.Byte "char" java.lang.Character}]
-    (vary-meta param assoc :tag (or (boxed-primitive (.getName type)) type))))
+    (vary-meta sym assoc :tag (or (boxed-primitive (.getName type)) type))))
 
-(defn build-params [use-type-hinting spec]
+(defn- build-params
+  "Given a method spec returns a list of symbols to be used as function
+  parameters (type-hinting them if necessary)"
+  [spec use-type-hinting]
   (let [params (->> spec
                     :param-count
                     range
                     (map gensym)
                     vec)]
     (if (and use-type-hinting (not (:disable-hinting spec)))
-      (map hint-param params (:param-types spec))
+      (map hint-symbol params (:param-types spec))
       params)))
 
 (defn- build-arity
-  "TODO"
+  "Giving a spec builds the arity part of a fn, i.e.: `([params] body)."
   [instance no-currying use-type-hinting spec]
   (let [raw-method-symbol (symbol (str "." (:raw-name spec)))
-        params (build-params use-type-hinting spec)
+        params (build-params spec use-type-hinting)
         is-void (:is-void spec)]
     (cond
-     ;; define function for static method
+     ;; arity for static method
      (:is-static spec)
      (let [static-method-symbol (symbol (str (:class-name spec) "/" (:raw-name spec)))]
        `([~@params] (~static-method-symbol ~@params)))
-     ;; define non-curried function
+     ;; arity for non-curried function
      no-currying
      `([this# ~@params]
        (let [result# (~raw-method-symbol this# ~@params)]
          (if ~is-void
            this#
            result#)))
-     ;; define curried function
+     ;; arity for curried function
      :else
      `([~@params]
        (let [result# (~raw-method-symbol @~instance ~@params)]


;; TODO better interop by coercing argument types

(defn- method-specs [^java.lang.Class c]
  (->> c
       .getDeclaredMethods
       (filter is-public)

           @~instance
           result#))))))

(defn- build-function
  "Builds a fn definition with n arities, where n is (count specs).
  The function will curry the target-sym unless no-currying is true.  If
  type-hinting is true, type-hinted all the function parameters (unless
  the spec forbids it with :disable-hinting)."
  [target-sym no-currying type-hinting [fn-name specs]]
  (let [fn-symbol (symbol fn-name)
        arity-fn (partial build-arity target-sym no-currying type-hinting)]
    `(defn ~fn-symbol ~@(map arity-fn specs))))

(defn- define-symbol
