Start using codox to generate API documentation.

Document all of the functions in the process.

Author: conormcd

project.clj

@@ -6,6 +6,7 @@
   :pedantic? :abort
   :dependencies [[org.clojure/clojure "1.7.0"]
                  [net.n01se/clojure-jna "1.0.0"]]
+  :profiles {:dev {:plugins [[lein-codox "0.9.1"]]}}
   :deploy-repositories ^:replace [["clojars" {:url "https://clojars.org/repo"
                                               :username [:gpg :env/clojars_username]
                                               :password [:gpg :env/clojars_password]

src/clj_libssh2/agent.clj

@@ -1,12 +1,25 @@
 (ns clj-libssh2.agent
+  "Functions for interacting with an SSH agent. The agent is expected to be
+   available on the UNIX domain socket referred to by the SSH_AUTH_SOCK
+   environment variable."
   (:require [clj-libssh2.error :refer [handle-errors with-timeout]]
-            [clj-libssh2.libssh2 :as libssh2]
             [clj-libssh2.libssh2.agent :as libssh2-agent])
   (:import [com.sun.jna.ptr PointerByReference]))
 
 (defn- get-identity
   "Get the next available identity from the agent. Pass nil for previous to get
-   the first entry."
+   the first entry.
+
+   Arguments:
+
+   session    A clj-libssh2.session.Session object.
+   ssh-agent  An ssh agent object from libssh2_agent_init.
+   previous   The last identity returned from a call to this function. Pass nil
+              to get the first entry.
+
+   Return:
+
+   A native object as returned by libssh2_agent_get_identity."
   [session ssh-agent previous]
   (when (nil? previous)
     (handle-errors session
@@ -22,7 +35,18 @@
       (throw (Exception. "An unknown error occurred")))))
 
 (defn authenticate
-  "Attempt to authenticate a session using the agent."
+  "Attempt to authenticate a session using the agent.
+
+   Arguments:
+
+   session  A clj-libssh2.session.Session object which refers to a session
+            which has not already been authenticated.
+   username The username for the user who is trying to authenticate.
+
+   Return:
+
+   True on success. An exception will be thrown if the user could not be
+   authenticated."
   [session username]
   (let [ssh-agent (libssh2-agent/init (:session session))]
     (when (nil? ssh-agent)

src/clj_libssh2/authentication.clj

@@ -1,12 +1,16 @@
 (ns clj-libssh2.authentication
+  "Authenticate a session."
   (:require [clojure.java.io :refer [file]]
-            [clj-libssh2.libssh2.userauth :as libssh2-userauth]
-            [clj-libssh2.agent :as ssh-agent]
-            [clj-libssh2.error :refer [handle-errors with-timeout]])
+            [clj-libssh2.agent :as agent]
+            [clj-libssh2.error :refer [handle-errors with-timeout]]
+            [clj-libssh2.libssh2.userauth :as libssh2-userauth])
   (:import clojure.lang.PersistentArrayMap))
 
 (defprotocol Credentials
-  (valid? [credentials]))
+  "A datatype to represent a way of authentication and the necessary data to
+   use that authentication method."
+  (valid? [credentials]
+    "Check if this Credentials instance is internally consistent."))
 
 (defrecord AgentCredentials [username]
   Credentials
@@ -26,11 +30,25 @@
   (valid? [credentials] (and (some? username) (some? password))))
 
 (defmulti authenticate
+  "Authenticate a session.
+
+   Arguments:
+
+   session      A clj-libssh2.session.Session object referring to an SSH
+                session which has not yet been authenticated.
+   credentials  Either an instance of Credentials or a map which can be
+                transformed into a Credentials object.
+
+   Return:
+
+   True on success. An exception will be thrown if ther session could not be
+   authenticated."
+  {:arglists '([session credentials])}
   (fn [session credentials] (type credentials)))
 
 (defmethod authenticate AgentCredentials
   [session credentials]
-  (ssh-agent/authenticate session (:username credentials)))
+  (agent/authenticate session (:username credentials)))
 
 (defmethod authenticate KeyCredentials
   [session credentials]