docs: add missing docstrings and mark certain components as deprecated

14 files changed, 57 insertions, 9 deletions

diff --git a/src/weepinbell/config.clj b/src/weepinbell/config.clj
index 8500b32..d784e2c 100644
--- a/src/weepinbell/config.clj
+++ b/src/weepinbell/config.clj
@@ -1,4 +1,6 @@
 (ns weepinbell.config
+  "Config loader component that merges default config with user config.
+  Default config is located at resources/config.edn"
   (:require [clojure.edn :as edn]
             [clojure.java.io :as io]))
 
diff --git a/src/weepinbell/core.clj b/src/weepinbell/core.clj
index f56a5b5..0c96b5b 100644
--- a/src/weepinbell/core.clj
+++ b/src/weepinbell/core.clj
@@ -1,4 +1,5 @@
 (ns weepinbell.core
+  "Main component that loads resources and start other components."
   (:require [org.httpkit.server :refer [run-server]]
             [clojure.spec.alpha :as s]
             [weepinbell.processor :as processor]
@@ -11,14 +12,22 @@
             [weepinbell.storage.spec])
   (:gen-class)) ;; Essential for "lein uberjar"
 
-(def wmc (chan))
+(def ^{:doc "Webmention channel.
+       Receiver puts webmention requests in. Processor takes them out."}
+  wmc (chan))
 
-(def config (load-config))
+(def ^{:doc "Weepinbell configuration, 
+       loaded from config.edn and merged with defaults."}
+  config (load-config))
 
-(def store (s/conform :weepinbell.storage.spec/vtable
+(def ^{:doc "Storage middle layer, a map of data-manipulating functions.
+       Supports various storage as long as the map conforms storage.spec."}
+  store (s/conform :weepinbell.storage.spec/vtable
                       (edn/use-store (:data-path config))))
 
-(def hooks (let [hooks [:on-receive :on-update :on-delete :on-create]
+(def ^{:doc "Hooks, a map of callback functions that processor calls 
+       on certain events. Can be used for webhooks and more."}
+  hooks (let [hooks [:on-receive :on-update :on-delete :on-create]
                  webhooks (:webhook config)]
              (zipmap hooks
                      (map (fn [hook] #(webhook/trigger hook webhooks))
diff --git a/src/weepinbell/feed.clj b/src/weepinbell/feed.clj
index aa118c5..900dc00 100644
--- a/src/weepinbell/feed.clj
+++ b/src/weepinbell/feed.clj
@@ -1,10 +1,11 @@
 (ns weepinbell.feed
+  "Handler of route /feed/:domain. Generating RSS feed for each domain."
   (:require [clj-rss.core :as rss]
             [weepinbell.utils.url :refer [get-domain]]
             [weepinbell.utils.digest :refer [digest]])
   (:import [java.time Instant]))
 
-(defn make-feed-items [wms config]
+(defn- make-feed-items [wms config]
   (->> wms
        (map #(let [wm (:webmention %)
                    id (if-let [id (:id wm)] id
@@ -20,7 +21,7 @@
        (take-last (:feed-length config))
        doall))
 
-(defn make-feed-channel [title desc link wms config]
+(defn- make-feed-channel [title desc link wms config]
   (rss/channel-xml
    {:title title
     :link link
@@ -28,6 +29,7 @@
    (when wms (make-feed-items wms config))))
 
 (defn rss
+  "Generate RSS XML response, or 404 JSON response when not found."
   [domain storage config]
   (if ((set (:allowed-target-domains config)) domain)
     (let [wms ((:get-by-domain storage) domain)]
diff --git a/src/weepinbell/handler.clj b/src/weepinbell/handler.clj
index b4b9576..0970f8c 100644
--- a/src/weepinbell/handler.clj
+++ b/src/weepinbell/handler.clj
@@ -1,4 +1,6 @@
 (ns weepinbell.handler
+  "Handler define routes and wrap responses. It pass request to other specific handlers.
+  Other handlers are receiver, retriever and feed."
   (:require [compojure.core :refer [routes POST GET context]]
             [compojure.route :as route]
             [ring.middleware.defaults :refer [wrap-defaults api-defaults]]
diff --git a/src/weepinbell/microformats/parser.clj b/src/weepinbell/microformats/parser.clj
index b057d07..4a256c3 100644
--- a/src/weepinbell/microformats/parser.clj
+++ b/src/weepinbell/microformats/parser.clj
@@ -1,4 +1,8 @@
+;; DEPRECATED !!!
+
 (ns weepinbell.microformats.parser
+  "Deprecated. See issue #20
+  https://codeberg.org/eltrac/weepinbell/issues/20"
   (:require [clojure.string :refer [includes? lower-case]]
             [taoensso.timbre :as timbre])
   (:import [com.kylewm.mf2j Mf2Parser]
diff --git a/src/weepinbell/microformats/wrapper.clj b/src/weepinbell/microformats/wrapper.clj
index fdf8bbd..a004aea 100644
--- a/src/weepinbell/microformats/wrapper.clj
+++ b/src/weepinbell/microformats/wrapper.clj
@@ -1,4 +1,8 @@
+;; DEPRECATED !!!
+
 (ns weepinbell.microformats.wrapper
+  "Deprecated. See issue #20
+  https://codeberg.org/eltrac/weepinbell/issues/20"
   (:require [weepinbell.utils :refer [javamap->map]]
             [taoensso.timbre :as timbre]
             [clojure.spec.alpha :as s]))
diff --git a/src/weepinbell/receiver.clj b/src/weepinbell/receiver.clj
index 8a77aad..7e62a16 100644
--- a/src/weepinbell/receiver.clj
+++ b/src/weepinbell/receiver.clj
@@ -1,5 +1,6 @@
 (ns weepinbell.receiver
-  "Receiver receives Webmention request (a source and a target); verify the request; return error message if any; push Webmention into queue of processor."
+  "Handler of route /endpoint or any other route the user configured. 
+  Receiver receives Webmention request (a source and a target); verify the request; return error message if any; push Webmention into webbmention channel for processor to take."
   (:require [clojure.string :as string]
             [clojure.core.async :refer [put!]]
             [weepinbell.utils.url :refer [get-domain valid-http-url?]]
@@ -41,7 +42,8 @@
 ;; receiving logic
 
 (defn receive
-  "Receive webmention; call verify-request; if verification passed, push webmention into queue."
+  "Receive webmention; call verify-request; if verification passed, push webmention into queue.
+  Return JSON response of pending notification, rejection or error."
   [wm wmc config]
   (let [{:keys [s t]} wm
         source (remove-anchor s)
diff --git a/src/weepinbell/retriever.clj b/src/weepinbell/retriever.clj
index 3c42011..bb3ff7d 100644
--- a/src/weepinbell/retriever.clj
+++ b/src/weepinbell/retriever.clj
@@ -1,4 +1,6 @@
 (ns weepinbell.retriever
+  "Handler of routes /api/mention/:id, /api/mentions/...
+  Retriever gets webmention form storage and wraps it in a response."
   (:require [weepinbell.utils.url :refer [get-domain]]
             [weepinbell.microformats.wrapper :as mf-wrapper]))
 
diff --git a/src/weepinbell/storage/edn_storage.clj b/src/weepinbell/storage/edn_storage.clj
index 36292c8..1cee975 100644
--- a/src/weepinbell/storage/edn_storage.clj
+++ b/src/weepinbell/storage/edn_storage.clj
@@ -1,4 +1,6 @@
 (ns weepinbell.storage.edn-storage
+  "EDN file-based storage middle layer.
+  Entry function is use-store, which makes a valid storage vtable."
   (:require [clojure.edn :as edn]
             [weepinbell.utils :refer [file-exists?]]
             [weepinbell.utils.url :refer [get-domain get-target get-path]]
diff --git a/src/weepinbell/storage/spec.clj b/src/weepinbell/storage/spec.clj
index dfb4458..d7d6469 100644
--- a/src/weepinbell/storage/spec.clj
+++ b/src/weepinbell/storage/spec.clj
@@ -1,5 +1,10 @@
 (ns weepinbell.storage.spec

+  "Spec of storage middle layer, which is a vtable/map of storage functions.

+  The spec makes sure any map is a valid storage vtable."

   (:require [clojure.spec.alpha :as s]))

 

 (s/def ::vtable

   (s/keys :req-un [::append ::update ::delete ::get ::get-by-domain]))

+

+;; TODO Needs to define specs for ::append ::update and other keys.

+;; make sure they're functions and has the right paramters.

diff --git a/src/weepinbell/ui.clj b/src/weepinbell/ui.clj
index 08a769e..3afa674 100644
--- a/src/weepinbell/ui.clj
+++ b/src/weepinbell/ui.clj
@@ -1,4 +1,8 @@
+;; DEPRECATED !!!
+
 (ns weepinbell.ui
+  "This component is deprecated.
+  Frontend will be refactored. See issue #8"
   (:require [hiccup2.core :as h]
             [weepinbell.utils :refer [format-list]]))
 
diff --git a/src/weepinbell/utils.clj b/src/weepinbell/utils.clj
index 6b862ab..0b106d5 100644
--- a/src/weepinbell/utils.clj
+++ b/src/weepinbell/utils.clj
@@ -1,4 +1,8 @@
+;; DEPRECATED !!!
+
 (ns weepinbell.utils
+  "This componets is deprecated.
+  All functions in this namespace will be moved or rewritten."
   (:require [weepinbell.http.client :as client]
             [clojure.string :as string]
             [clojure.walk :as walk]
diff --git a/src/weepinbell/webhook.clj b/src/weepinbell/webhook.clj
index 6ff532d..da98cec 100644
--- a/src/weepinbell/webhook.clj
+++ b/src/weepinbell/webhook.clj
@@ -1,4 +1,7 @@
 (ns weepinbell.webhook
+  "Makes hooks for sending webhook requests to certain endpoints on certain events.
+  This component does not care about specific event types or endpoints.
+  It takes them from its caller (core.clj) and makes a map of hook functions."
   (:require [taoensso.timbre :as timbre]
             [weepinbell.utils.url :refer [valid-http-url?]]
             [weepinbell.http.client :as client]))
diff --git a/src/weepinbell/wrapper.clj b/src/weepinbell/wrapper.clj
index add58be..39f4ba2 100644
--- a/src/weepinbell/wrapper.clj
+++ b/src/weepinbell/wrapper.clj
@@ -1,4 +1,6 @@
 (ns weepinbell.wrapper
+  "Wrapper component wraps a qualified webmention while processing, used by processor.
+  It adds microformats and extra data and return complete webmention map ready for storage."
   (:require [weepinbell.utils :refer [javamap->map
                                       file-exists?
                                       download-file]]
@@ -56,7 +58,8 @@
 
 ;;;; main function
 (defn wrap
-  "Parse microformats and collect essential info. Wrap source, target and collected data into a Clojure map and return it."
+  "Parse microformats and collect essential info. 
+  Wrap source, target and collected data into a map and return it."
   [source target base-url]
   (let [mf (-> source
                mf-parser/parse