Merge pull request #12 from asafch/documentation

Documentation overhaul

.gitignore

@@ -16,3 +16,4 @@ pom.xml.asc
 .lsp
 .settings
 .project
+.idea

.travis.yml

@@ -13,7 +13,7 @@ jobs:
         - stage: build
           script: lein javac
         - stage: test
-          script: lein do clean, javac, test
+          script: lein do clean, test
 after_success:
     - bash -ex test/coveralls.sh
 notifications:

project.clj

@@ -1,14 +1,14 @@
-(defproject unleash-client-clojure "0.2.0"
+(defproject unleash-client-clojure "0.2.1"
   :description "A Clojure library wrapping https://github.com/Unleash/unleash-client-java"
   :url "https://github.com/AppsFlyer/unleash-client-clojure"
   :license {:name "EPL-2.0 OR GPL-2.0-or-later WITH Classpath-exception-2.0"
-            :url "https://www.eclipse.org/legal/epl-2.0/"}
+            :url  "https://www.eclipse.org/legal/epl-2.0/"}
   :dependencies [[no.finn.unleash/unleash-client-java "3.3.3"]]
   :profiles {:dev {:dependencies [[org.clojure/clojure "1.10.1"]
                                   [clj-kondo "RELEASE"]
                                   [org.apache.logging.log4j/log4j-core "2.11.2"]]
-                    :aliases      {"clj-kondo" ["run" "-m" "clj-kondo.main"]
-                                   "lint"      ["run" "-m" "clj-kondo.main" "--lint" "src" "test"]}
-                    :plugins     [[lein-ancient "0.6.15"]
+                   :aliases      {"clj-kondo" ["run" "-m" "clj-kondo.main"]
+                                  "lint"      ["run" "-m" "clj-kondo.main" "--lint" "src" "test"]}
+                   :plugins      [[lein-ancient "0.6.15"]
                                   [lein-cloverage "1.2.0"]]
-                    :global-vars {*warn-on-reflection* true}}})
+                   :global-vars  {*warn-on-reflection* true}}})

src/unleash_client_clojure/builder.clj

@@ -1,71 +1,142 @@
 (ns unleash-client-clojure.builder
+  "Create and configure builders that build instances of UnleashConfig."
   (:import [no.finn.unleash CustomHttpHeadersProvider UnleashContextProvider]
            [no.finn.unleash.util UnleashConfig UnleashConfig$Builder UnleashScheduledExecutor]
            [no.finn.unleash.event UnleashSubscriber]))
 
-(defn build ^UnleashConfig [& fs]
-  (let [bldr (UnleashConfig$Builder.)]
+(defn build
+  "Expects to be applied with a variadic number of arguments, each of which is a function that expects an
+  UnleashConfig$Builder instance.
+  Returns an instance of UnleashConfig that had all of its parameters set by said functions.
+
+  Using this building pattern allows users to manipulate the builder instance in ways that aren't
+  implemented in this library by passing a function that expects an UnleashConfig$Builder.
+
+  Example:
+  (build (app-name \"test-app\")
+         (unleash-api \"http://example.unleash.com/api\"))"
+  ^UnleashConfig [& builder-param-setters]
+  (let [builder (UnleashConfig$Builder.)]
     (.build ^UnleashConfig$Builder
             (reduce
               (fn
-                ([] bldr)
-                ([bldr f]
-                 (f bldr)))
-              bldr
-              fs))))
-
-(defn app-name [^String name]
-  (fn [^UnleashConfig$Builder bldr]
-    (.appName bldr name)))
-
-(defn instance-id [^String id]
-  (fn [^UnleashConfig$Builder bldr]
-    (.instanceId bldr id)))
-
-(defn unleash-api [^String api]
-  (fn [^UnleashConfig$Builder bldr]
-    (.unleashAPI bldr api)))
-
-(defn custom-http-header [header-name header-value]
-  (fn [^UnleashConfig$Builder bldr]
-    (.customHttpHeader bldr header-name header-value)))
-
-(defn send-metrics-interval [^Long interval-seconds]
-  (fn [^UnleashConfig$Builder bldr]
-    (.sendMetricsInterval bldr interval-seconds)))
-
-(defn fetch-toggles-interval [^Long interval-seconds]
-  (fn [^UnleashConfig$Builder bldr]
-    (.fetchTogglesInterval bldr interval-seconds)))
-
-(defn synchronous-fetch-on-initialisation [enable?]
-  (fn [^UnleashConfig$Builder bldr]
-    (.synchronousFetchOnInitialisation bldr enable?)))
-
-(defn enable-proxy-authentication-by-jvm-properties []
-  (fn [^UnleashConfig$Builder bldr]
-    (.enableProxyAuthenticationByJvmProperties bldr)))
-
-(defn backup-file [^String backup-file]
-  (fn [^UnleashConfig$Builder bldr]
-    (.backupFile bldr backup-file)))
-
-(defn environment [^String environment]
-  (fn [^UnleashConfig$Builder bldr]
-    (.environment bldr environment)))
-
-(defn custom-http-header-provider [^CustomHttpHeadersProvider provider]
-  (fn [^UnleashConfig$Builder bldr]
-    (.customHttpHeadersProvider bldr provider)))
-
-(defn unleash-context-provider [^UnleashContextProvider provider]
-  (fn [^UnleashConfig$Builder bldr]
-    (.unleashContextProvider bldr provider)))
-
-(defn scheduled-executor [^UnleashScheduledExecutor executor]
-  (fn [^UnleashConfig$Builder bldr]
-    (.scheduledExecutor bldr executor)))
-
-(defn subscriber [^UnleashSubscriber subscriber]
-  (fn [^UnleashConfig$Builder bldr]
-    (.subscriber bldr subscriber)))
+                ([] builder)
+                ([builder set-builder-param]
+                 (set-builder-param builder)))
+              builder
+              builder-param-setters))))
+
+(defn app-name
+  "Expects an application name.
+  Returns a function that expects an UnleashConfig$Builder, and sets the appName property of the builder."
+  [^String name]
+  (fn [^UnleashConfig$Builder builder]
+    (.appName builder name)))
+
+(defn instance-id
+  "Expects an instance ID.
+  Returns a function that expects an UnleashConfig$Builder, and sets the instanceId property of the builder."
+  [^String id]
+  (fn [^UnleashConfig$Builder builder]
+    (.instanceId builder id)))
+
+(defn unleash-api
+  "Expects a URL for an Unleash server.
+  Returns a function that expects an UnleashConfig$Builder, and sets the unleashAPI property of the builder."
+  [^String api]
+  (fn [^UnleashConfig$Builder builder]
+    (.unleashAPI builder api)))
+
+(defn custom-http-header
+  "Expects an HTTP header name and value.
+  Returns a function that expects an UnleashConfig$Builder, and adds the relevant HTTP header name and value to the headers used by the builder.
+  These headers would be added to outgoing HTTP requests sent by the Unleash client to the Unleash server.
+
+  Can be used multiple times to set multiple headers.
+
+  Example:
+  (build [(unleash-api \"http://example.unleash.com/api\")
+          (custom-http-header \"X-AF-HEADER-1\" \"a\")
+          (custom-http-header \"X-AF-HEADER-2\" \"b\")
+          (custom-http-header \"X-AF-HEADER-3\" \"c\")])"
+  [header-name header-value]
+  (fn [^UnleashConfig$Builder builder]
+    (.customHttpHeader builder header-name header-value)))
+
+(defn send-metrics-interval
+  "Expects a long that marks the interval (in seconds) of sending metrics.
+  Returns a function that expects an UnleashConfig$Builder, and sets the sendMetricsInterval property of the builder."
+  [^Long interval-seconds]
+  (fn [^UnleashConfig$Builder builder]
+    (.sendMetricsInterval builder interval-seconds)))
+
+(defn fetch-toggles-interval
+  "Expects a long that marks the interval (in seconds) of fetching toggles' states from the Unleash server.
+  Returns a function that expects an UnleashConfig$Builder, and sets the fetchTogglesInterval property of the builder."
+  [^Long interval-seconds]
+  (fn [^UnleashConfig$Builder builder]
+    (.fetchTogglesInterval builder interval-seconds)))
+
+(defn synchronous-fetch-on-initialisation
+  "Expects a boolean that controls if toggles are fetched synchronously when the Unleash client is initialised.
+  Returns a function that expects an UnleashConfig$Builder, and sets the synchronousFetchOnInitialisation property of
+  the builder."
+  [enable?]
+  (fn [^UnleashConfig$Builder builder]
+    (.synchronousFetchOnInitialisation builder enable?)))
+
+(defn enable-proxy-authentication-by-jvm-properties
+  "Expects a boolean that controls if authentication against an HTTP proxy would use the JVM settings http.proxyUser and
+  http.proxyPassword.
+  Returns a function that expects an UnleashConfig$Builder, and sets the isProxyAuthenticationByJvmProperties property of the builder."
+  []
+  (fn [^UnleashConfig$Builder builder]
+    (.enableProxyAuthenticationByJvmProperties builder)))
+
+(defn backup-file
+  "Expects a backup file path, into which the Unleash client would backup its state to be used when the Unleash server
+  is unavailable. By defeault this would be unleash-repo.json in the directory set by the JVM property java.io.tmpdir.
+  Returns a function that expects an UnleashConfig$Builder, and sets the backupFile property of the builder."
+  [^String backup-file]
+  (fn [^UnleashConfig$Builder builder]
+    (.backupFile builder backup-file)))
+
+(defn environment
+  "Expects an application environment.
+  Returns a function that expects an UnleashConfig$Builder, and sets the environment property of the builder."
+  [^String environment]
+  (fn [^UnleashConfig$Builder builder]
+    (.environment builder environment)))
+
+(defn custom-http-header-provider
+  "Expects an instance of CustomHttpHeadersProvider, which adds headers to outgoing HTTP requests that are sent to the
+  Unleash server, based on the contents of the request itself.
+  Returns a function that expects an UnleashConfig$Builder, and sets the custom-http-headers-provider property of the
+  builder."
+  [^CustomHttpHeadersProvider provider]
+  (fn [^UnleashConfig$Builder builder]
+    (.customHttpHeadersProvider builder provider)))
+
+
+(defn unleash-context-provider
+  "Expects an instance of UnleashContextProvider, which would provide the context for calls of enabled? instead of
+  having it provided as an arguments in the call site.
+  Returns a function that expects an UnleashConfig$Builder, and sets the contextProvider property of the builder."
+  [^UnleashContextProvider provider]
+  (fn [^UnleashConfig$Builder builder]
+    (.unleashContextProvider builder provider)))
+
+(defn scheduled-executor
+  "Expects an instance of UnleashScheduledExecutor, which would be used to periodically send usage metrics. The interval
+  of sending those metrics can be set with 'send-metrics-interval'.
+  Returns a function that expects an UnleashConfig$Builder, and sets the scheduledExecutor property of the builder."
+  [^UnleashScheduledExecutor executor]
+  (fn [^UnleashConfig$Builder builder]
+    (.scheduledExecutor builder executor)))
+
+(defn subscriber
+  "Expects an instance of UnleashSubscriber, which would be notified when the Unleash client's internal state changes.
+  Returns a function that expects an UnleashConfig$Builder, and sets the subscriber property of the builder."
+  [^UnleashSubscriber subscriber]
+  (fn [^UnleashConfig$Builder builder]
+    (.subscriber builder subscriber)))

src/unleash_client_clojure/context.clj

@@ -1,60 +1,112 @@
 (ns unleash-client-clojure.context
+  "Create and configure builders that build instances of UnleashContext."
   (:import [no.finn.unleash UnleashContext UnleashContext$Builder]))
 
-(defn build ^UnleashContext
-  [& fs]
-  (let [bldr (UnleashContext$Builder.)]
+(defn build
+  "Expects to be applied with a variadic number of arguments, each of which is a function that expects an
+  UnleashContext$Builder instance.
+  Returns an instance of UnleashContext that had all of its parameters set by said functions.
+
+  Using this building pattern allows users to manipulate the builder instance in ways that aren't
+  implemented in this library by passing a function that expects an UnleashContext$Builder.
+
+  Example:
+  (build (app-name \"test-app\")
+         (environment \"STG\"))
+
+  The UnleashContext instance can be attached to an Unleash client via
+  unleash-client-clojure.builder/unleash-context-provider."
+  ^UnleashContext
+  [& builder-param-setters]
+  (let [builder (UnleashContext$Builder.)]
     (.build ^UnleashContext$Builder
             (reduce
               (fn
-                ([] bldr)
-                ([bldr f]
-                 (f bldr)))
-              bldr
-              fs))))
+                ([] builder)
+                ([builder set-builder-param]
+                 (set-builder-param builder)))
+              builder
+              builder-param-setters))))
 
-(defn get-app-name [^UnleashContext ctx]
+(defn get-app-name
+  "Returns the app's name from the context."
+  [^UnleashContext ctx]
   (.get (.getAppName ctx)))
 
-(defn get-environment [^UnleashContext ctx]
+(defn get-environment
+  "Returns the environment from the context."
+  [^UnleashContext ctx]
   (.get (.getEnvironment ctx)))
 
-(defn get-user-id [^UnleashContext ctx]
+(defn get-user-id
+  "Returns the user ID from the context."
+  [^UnleashContext ctx]
   (.get (.getUserId ctx)))
 
-(defn get-session-id [^UnleashContext ctx]
+(defn get-session-id
+  "Returns the session ID from the context."
+  [^UnleashContext ctx]
   (.get (.getSessionId ctx)))
 
-(defn get-remote-address [^UnleashContext ctx]
+(defn get-remote-address
+  "Returns the remote address from the context."
+  [^UnleashContext ctx]
   (.get (.getRemoteAddress ctx)))
 
-(defn get-property [^UnleashContext ctx ^String property-name]
+(defn get-property
+  "Returns a context property"
+  [^UnleashContext ctx ^String property-name]
   (.get (.getProperties ctx) property-name))
 
-(defn get-by-name [^UnleashContext ctx ^String contextName]
+(defn get-by-name
+  "Returns a context property, explicitly looking for:
+  - environment
+  - appName
+  - userId
+  - sessionId
+  - remoteAddress
+  Otherwise, behaves as 'get-property'."
+  [^UnleashContext ctx ^String contextName]
   (.get (.getByName ctx contextName)))
 
-(defn app-name [^String app-name]
-  (fn [^UnleashContext$Builder bldr]
-    (.appName bldr app-name)))
-
-(defn environment [^String environment]
-  (fn [^UnleashContext$Builder bldr]
-    (.environment bldr environment)))
+(defn app-name
+  "Expects an application's name.
+  Returns a function that expects an UnleashContext$Builder, and sets the appName property of the builder."
+  [^String app-name]
+  (fn [^UnleashContext$Builder builder]
+    (.appName builder app-name)))
 
-(defn user-id [^String id]
-  (fn [^UnleashContext$Builder bldr]
-    (.userId bldr id)))
+(defn environment
+  "Expects an application environment.
+  Returns a function that expects an UnleashContext$Builder, and sets the environment property of the builder."
+  [^String environment]
+  (fn [^UnleashContext$Builder builder]
+    (.environment builder environment)))
 
-(defn session-id [^String id]
-  (fn [^UnleashContext$Builder bldr]
-    (.sessionId bldr id)))
+(defn user-id
+  "Expects a user ID.
+  Returns a function that expects an UnleashContext$Builder, and sets the userId property of the builder."
+  [^String id]
+  (fn [^UnleashContext$Builder builder]
+    (.userId builder id)))
 
-(defn remote-address [^String address]
-  (fn [^UnleashContext$Builder bldr]
-    (.remoteAddress bldr address)))
+(defn session-id
+  "Expects a session ID.
+  Returns a function that expects an UnleashContext$Builder, and sets the sessionId property of the builder."
+  [^String id]
+  (fn [^UnleashContext$Builder builder]
+    (.sessionId builder id)))
 
-(defn add-property [^String name ^String value]
-  (fn [^UnleashContext$Builder bldr]
-    (.addProperty bldr name value)))
+(defn remote-address
+  "Expects a remote address (IP address). Used by RemoteAddressStrategy.
+  Returns a function that expects an UnleashContext$Builder, and sets the remoteAddress property of the builder."
+  [^String address]
+  (fn [^UnleashContext$Builder builder]
+    (.remoteAddress builder address)))
 
+(defn add-property
+  "Expects a property name-value pair.
+  Returns a function that expects an UnleashContext$Builder, and adds the key-value pair to the context's properties."
+  [^String name ^String value]
+  (fn [^UnleashContext$Builder builder]
+    (.addProperty builder name value)))