Adds doc

2 files changed, 27 insertions, 11 deletions

diff --git a/src/clj/queue_api/db/core.clj b/src/clj/queue_api/db/core.clj
index 765ce39..63446d8 100644
--- a/src/clj/queue_api/db/core.clj
+++ b/src/clj/queue_api/db/core.clj
@@ -13,13 +13,17 @@
 (mount/defstate conn
                 :start (d/create-conn schema))
 
-(defn add-agent [{:keys [id name primary-skillset secondary-skillset]}]
+(defn add-agent
+  "Add an agent into the database"
+  [{:keys [id name primary-skillset secondary-skillset]}]
   (d/transact! queue-api.db.core/conn [{:agent/id                 id
                                         :agent/name               name
                                         :agent/primary-skillset   primary-skillset
                                         :agent/secondary-skillset secondary-skillset}]))
 
-(defn add-job [{:keys [id type urgent]}]
+(defn add-job
+  "Add a job into the database"
+  [{:keys [id type urgent]}]
   (d/transact! queue-api.db.core/conn [{:job/id     id
                                         :job/type   type
                                         :job/urgent urgent
@@ -29,12 +33,13 @@
 (defn request-job [id]
   {:job_request {:job_id "Dummy" :agent_id "Dummy"}})
 
-
 (defn get-agent [id]
   [{:type "Dummy"
     :jobs -2}])
 
-(defn agent-jobs [id s]
+(defn agent-jobs
+  "Get a job that has a agent bounded with given `id` and a status of `s`"
+  [id s]
   (let [q (d/q '[:find ?jid
                  :in $ ?id ?s
                  :where
@@ -45,8 +50,12 @@
                @conn id s)]
     (map #(d/entity @conn [:job/id (first %)]) q)))
 
-
-(defn q-job [u s t]
+(defn q-job
+  "Fetch job and order by date
+  `u`: if it is flagged urgent
+  `s` status of the job
+  `t` type of the job"
+  [u s t]
   (let [q (->> (d/q '[:find ?d ?id
                       :in $ ?u ?s ?t
                       :where
@@ -59,14 +68,18 @@
                (sort-by first))]
     (map #(d/entity @conn [:job/id (last %)]) q)))
 
-(defn q-status [s]
+(defn q-status
+  "Query job filtering only by status"
+  [s]
   (d/q '[:find ?id :in $ ?status
          :where
          [?e :job/status ?status]
          [?e :job/id ?id]]
        @conn s))
 
-(defn sum-queue []
+(defn sum-queue
+  "Count all job aggregated by type"
+  []
   {:completed  (map #(first %) (q-status :completed))
    :processing (map #(first %) (q-status :processing))
    :unassigned (map #(first %) (q-status :unassigned))})
\ No newline at end of file
diff --git a/src/clj/queue_api/routes/services.clj b/src/clj/queue_api/routes/services.clj
index 5d6d6cb..7e9fc98 100644
--- a/src/clj/queue_api/routes/services.clj
+++ b/src/clj/queue_api/routes/services.clj
@@ -12,6 +12,7 @@
                            :description "Manages agent resources"}}}}
 
   (context "/agent" []
+    :tags ["agent"]
     (PUT "/" []
       :body-params [id :- String, name :- String, primary_skillset :- [String], secondary_skillset :- [String]]
       :summary "Add a new agent"
@@ -24,10 +25,11 @@
     (POST "/" []
       :return [{:type String :jobs s/Int}]
       :body-params [agent_id :- String]
-      :summary "Get a summary of an agent"
+      :summary "Get summary of an agent"
       (ok (db/get-agent agent_id))))
 
   (context "/job" []
+    :tags ["job"]
     (PUT "/" []
       :body-params [id :- String, type :- String, urgent :- Boolean]
       :summary "Add a new job"
@@ -38,15 +40,16 @@
     (POST "/" []
       :return {:job_request {:job_id String :agent_id String}}
       :body-params [agent_id :- String]
-      :summary "Request a job for a agent"
+      :summary "Request a job to a given agent"
       (ok (db/request-job agent_id))))
 
   (context "/queue" []
+    :tags ["queue"]
     (GET "/" []
       :return {:completed [String]
                :processing[String]
                :unassigned [String]}
-      :summary "Get a summary of an agent"
+      :summary "Get a summary of the queue"
       (ok (db/sum-queue)))))