3 files changed, 29 insertions(+), 23 deletions(-)

M doc/cljdoc.edn
M doc/development.adoc
M doc/user-guide.adoc

@@ 1,5 1,5 @@
 {:cljdoc.doc/tree
  [["Readme" {:file "README.md"}]
-  ["Release Notes" {:file "CHANGELOG.md"}]
   ["User Guide" {:file "doc/user-guide.adoc"}]
+  ["Release Notes" {:file "CHANGELOG.md"}]
   ["Development" {:file "doc/development.adoc"}]]}

@@ 1,6 1,6 @@
 == Development
 
-Run tests:
+=== Running tests
 
 [source,sh]
 ----

@@ 3,9 3,13 @@
 https://branca.io/[Branca homepage] describes Branca as follows:
 
 [quote]
-----
-Branca is a secure easy to use token format which makes it hard to shoot yourself in the foot. It uses IETF XChaCha20-Poly1305 AEAD symmetric encryption to create encrypted and tamperproof tokens. The encrypted token is base62 encoded which makes it URL safe. Payload itself is an arbitrary sequence of bytes.
-----
+____
+Branca is a secure easy to use token format which makes it hard to shoot
+yourself in the foot. It uses IETF XChaCha20-Poly1305 AEAD symmetric encryption
+to create encrypted and tamperproof tokens. The encrypted token is base62
+encoded which makes it URL safe. Payload itself is an arbitrary sequence of
+bytes.
+____
 
 clj-branca is a Clojure implementation of encoding and decoding Branca tokens.
 It is built on https://docs.lazycode.co/lazysodium/[Lazysodium] cryptography


@@ 29,15 33,15 @@ Add clj-branca to your project's dependencies:
 
 === Basic usage
 
-The main namespace of clj-branca is +clj-branca.core+. It is recommended to be
-required with the alias +branca+.
+The main namespace of clj-branca is `clj-branca.core`. It is recommended to be
+required with the alias `branca`.
 
 [source,clojure]
 ----
 (require '[clj-branca.core :as branca])
 ----
 
-You can encode payload into a token with +branca/encode+. The payload can be a
+You can encode payload into a token with `branca/encode`. The payload can be a
 byte array, a string, or anything else that can be converted into a byte array
 by the https://github.com/aleph-io/byte-streams[byte-streams] library. The
 tokens is returned as a string.


@@ 51,7 55,7 @@ tokens is returned as a string.
 ;; "XZ69WpRTqZgEOqCJqaOK4iOKGLkg505VSASQ8MMGWs3mn1p6U81FvB5rSLpKlIjkZTUIBC6KiHIboz"
 ----
 
-To decode the token, use +branca/decode+. It takes the token as a string
+To decode the token, use `branca/decode`. It takes the token as a string
 and returns the payload as a byte array.
 
 [source,clojure]


@@ 62,7 66,7 @@ and returns the payload as a byte array.
 
 The encryption key used is 32 bytes. It can be a byte array or anything that can
 be converted into a byte array. You can generate a new key with
-+clj-branca.crypto/generate-key+.
+`clj-branca.crypto/generate-key`.
 
 [source,clojure]
 ----


@@ 74,17 78,17 @@ be converted into a byte array. You can generate a new key with
 === Token timestamp and time to live
 
 Branca tokens contain a timestamp that indicates when the token was issued. To
-limit token lifetime, you can give +:ttl+ in seconds in the options map when
-calling +branca/decode+. For example, to limit token lifetime to an hour:
+limit token lifetime, you can give `:ttl` in seconds in the options map when
+calling `branca/decode`. For example, to limit token lifetime to an hour:
 
 [source,clojure]
 ----
 (branca/decode secret-key token {:ttl 3600})
 ----
 
-If the token is expired, +branca/decode+ <<error-handling,throws an exception>>.
+If the token is expired, `branca/decode` <<error-handling,throws an exception>>.
 If you need to implement more complex TTL logic, you can get the token timestamp
-along the payload by calling +branca/decode*+.
+along the payload by calling `branca/decode*`.
 
 [source,clojure]
 ----


@@ 98,21 102,23 @@ along the payload by calling +branca/decode*+.
 The return value includes the token version and the nonce as well. You probably
 won't need them for anything, but they're included for the sake of completeness.
 
-NOTE: There is only one Branca version, +0xBA+. This is represented as a
-      single-byte value. Because JVM bytes are _signed_, the value
-      is printed as +-70+ and not as +186+ as you might expect.
+****
+There is only one Branca version, `0xBA`. This is represented as a
+single-byte value. Because JVM bytes are _signed_, the value
+is printed as `-70` and not as `186` as you might expect.
+****
 
 [[error-handling]]
 === Error handling
 
 Whenever clj-branca encouters an error, such as a malformed or a tampered token,
-it throws a +clojure.lang.ExceptionInfo+ exception. The exception data contains
-the key +:type+ to indicate that the exception was thrown by clj-branca.
+it throws a `clojure.lang.ExceptionInfo` exception. The exception data contains
+the key `:type` to indicate that the exception was thrown by clj-branca.
 
 [options="header""]
 |===
-| +:type+ | explanation
-| +:clj-branca.core/invalid-key+    | The key must be a 32-byte byte array.
-| +:clj-branca.core/encode-failure+ | Encryption failed.
-| +:clj-branca.core/invalid-token+  | Decoding token failed.
+| `:type` | explanation
+| `:clj-branca.core/invalid-key`    | The key must be a 32-byte byte array.
+| `:clj-branca.core/encode-failure` | Encryption failed.
+| `:clj-branca.core/invalid-token`  | Decoding token failed.
 |===