From 12fcd137541c8813ecc7e2b87733799616b3337e Mon Sep 17 00:00:00 2001
From: Trolli Schmittlauch <t.schmittlauch@orlives.de>
Date: Wed, 9 Sep 2020 18:01:51 +0200
Subject: [PATCH] annotate the PostService server/ request-handler functions

---
 src/Hash2Pub/PostService.hs | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/src/Hash2Pub/PostService.hs b/src/Hash2Pub/PostService.hs
index 2abf3b8..3d1df68 100644
--- a/src/Hash2Pub/PostService.hs
+++ b/src/Hash2Pub/PostService.hs
@@ -167,6 +167,7 @@ postServer service = relayInbox service
         :<|> tagUnsubscribe service
 
 
+-- | delivery endpoint: receive posts of a handled tag and enqueue them for relaying
 relayInbox :: DHT d => PostService d -> Hashtag -> Text -> Handler NoContent
 relayInbox serv tag posts = do
     let
@@ -195,6 +196,7 @@ newtype UnhandledTagException = UnhandledTagException String
 
 instance Exception UnhandledTagException
 
+-- | delivery endpoint: receives a list of subscribers of tags and their outstanding queues for migration
 subscriptionDelivery :: DHT d => PostService d -> Integer -> Text -> Handler Text
 subscriptionDelivery serv senderID subList = do
     let
@@ -240,6 +242,7 @@ subscriptionDelivery serv senderID subList = do
           enqueueSubscription subscriberSTM (normaliseTag tag) sub postList leaseTime
 
 
+-- | endpoint for fetching a post by its ID
 postFetch :: PostService d -> Text -> Handler Text
 postFetch serv postID = do
     postSet <- liftIO . readTVarIO . ownPosts $ serv
@@ -249,6 +252,7 @@ postFetch serv postID = do
        else throwError $ err404 { errBody = "No post found with this ID" }
 
 
+-- | endpoint for fetching multiple posts of this instance by their IDs
 postMultiFetch :: PostService d -> Text -> Handler Text
 postMultiFetch serv postIDs = do
     let idList = Txt.lines postIDs
@@ -261,6 +265,7 @@ postMultiFetch serv postIDs = do
           ) "" idList
 
 
+-- | delivery endpoint: inbox for initially publishing a post at an instance
 postInbox :: PostService d -> Text -> Handler NoContent
 postInbox serv post = do
     -- extract contained hashtags
@@ -277,6 +282,7 @@ postInbox serv post = do
     pure NoContent
 
 
+-- | delivery endpoint: receive postIDs of a certain subscribed hashtag
 tagDelivery :: PostService d -> Text -> Text -> Handler Text
 tagDelivery serv hashtag posts = do
     let postIDs = Txt.lines posts
@@ -288,6 +294,8 @@ tagDelivery serv hashtag posts = do
             pure ()
     pure $ "Received a postID for tag " <> hashtag
 
+
+-- | receive subscription requests to a handled hashtag
 tagSubscribe :: DHT d => PostService d -> Text -> Maybe Text -> Handler Integer
 tagSubscribe serv hashtag origin = do
     responsible <- liftIO $ isResponsibleFor (baseDHT serv) (hashtagToId hashtag)
@@ -307,6 +315,7 @@ tagSubscribe serv hashtag origin = do
     pure $ round leaseTime
 
 
+-- | receive and handle unsubscription requests regarding a handled tag
 tagUnsubscribe :: DHT d => PostService d -> Text -> Maybe Text -> Handler Text
 tagUnsubscribe serv hashtag origin = do
     responsible <- liftIO $ isResponsibleFor (baseDHT serv) (hashtagToId hashtag)