Merge branch 'codox'

Fixes #8

Author: conormcd

.gitignore

@@ -9,3 +9,4 @@ pom.xml.asc
 /.nrepl-port
 .hgignore
 .hg/
+doc/api

README.md

@@ -17,6 +17,9 @@ parts to this library:
    should use this if you're transitioning code from `clj-ssh` to this
    library.
 
+Documentation for the latest release should always be available at:
+http://conormcd.github.io/clj-libssh2/
+
 ## clj-libssh2 API
 
 The primary public API for this library is the following set of functions:

project.clj

@@ -6,10 +6,12 @@
   :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]
                                               :sign-releases false}]]
+  :codox {:output-path "doc/api"}
   :jvm-opts ["-Xmx1g"
              "-XX:+TieredCompilation"
              "-XX:TieredStopAtLevel=1"])

release.sh

@@ -85,6 +85,29 @@ save_artifacts() {
   fi
 }
 
+update_api_docs() {
+  local _version
+  _version=$1
+
+  set -x
+  git config --global user.email "${GITHUB_USER}@users.noreply.github.com"
+  git config --global user.name "${GITHUB_USER}/${GITHUB_REPO} release.sh"
+  git clone -b gh-pages [email protected]:${GITHUB_USER}/${GITHUB_REPO}.git doc/api
+  lein codox
+  (
+    cd doc/api
+    cat > circle.yml <<EOF
+general:
+  branches:
+    ignore:
+      - gh-pages
+EOF
+    git add .
+    git commit -m "Docs for version ${_version}"
+    git push origin gh-pages
+  )
+}
+
 ensure_github_release_tool_installed() {
   local _cwd
   _cwd=$(pwd)
@@ -124,6 +147,10 @@ clojars_deploy() {
   lein deploy clojars 2>&1 | sed -e 's,^,  ,'
 }
 
+cleanup() {
+  git clean -ffdx
+}
+
 v=$(new_version)
 update_project_clj "${v}"
 build_jars
@@ -145,4 +172,8 @@ if [ "$(branch)" = "master" ]; then
 
   # Push to clojars
   clojars_deploy
+
+  # Push new docs
+  update_api_docs "${v}"
 fi
+cleanup

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]