improving documentation

haskell/lib/API.hs

@@ -34,6 +34,11 @@ import Environment  ( cleanEnvironment )
 
 
 
+{- |
+
+Haskell API
+
+-}
 data P2PRCapi = MkP2PRCapi
   { startServer       :: IOEitherError ProcessHandle
   , execInitConfig    :: IOEitherError P2prcConfig
@@ -57,6 +62,33 @@ data MapPortRequest =
     String -- ^ Network domain name
 
 
+{-|
+  This function cleans the previous running state (ensuring a pure P2PRC runtime state) and builds up a conditional 'P2PRCapi' instance.
+
+  __The following example show how this function can be used to expose the runtime functionalities:__
+
+  @
+  example :: IOEitherError P2PRCapi
+  example = do
+
+    eitherP2prcAPI <- getP2prcAPI
+
+    case eitherP2prcAPI of
+      ( Right
+        ( MkP2PRCapi
+          { startServer     = startServer
+          , execInitConfig  = execInitConfig
+          , execListServers = execListServers
+          , execMapPort     = execMapPort
+          }
+        )) -> do
+
+        -- Your code logic
+
+      errValue -> errValue
+  @
+-}
+{-# WARNING getP2prcAPI "This function is currently unstable since it assumes that the Haskell program is executed from the P2PRC \"haskell\" subfolder and the \"p2prc\" executable in the the root folder." #-}
 getP2prcAPI :: IOEitherError P2PRCapi
 getP2prcAPI = do
 

haskell/lib/CLI.hs

@@ -76,7 +76,7 @@ eitherExecProcess cmd opts input =
         (show input)
 
     pure $ case code of
-      ExitFailure i -> Left $ MkSystemError i cmd err
+      ExitFailure i -> Left $ MkCLISystemError i cmd err
       _             -> Right out
 
 

haskell/lib/Engine.hs

@@ -42,7 +42,19 @@ import API
 -- TODO: publish haskell library
 --
 
--- | Hello World
+{-|
+  This function starts and bootstraps the P2PRC runtime that associates the a specific host's machine port to a DNS address to expose a certain application to the P2PRC network. You will only need to also import the 'MkMapPortRequest' data constructor to represent the this port request.
+
+  __This example demonstrates how it can be ran on the IO context:__
+
+  @
+  example :: IO ()
+  example = do
+    runP2PRC
+      ( MkMapPortRequest 8080 "jose.akilan.io"
+      )
+  @
+-}
 runP2PRC :: MapPortRequest -> IO ()
 runP2PRC (MkMapPortRequest portNumber domainName) = do
 
@@ -76,15 +88,15 @@ runP2PRC (MkMapPortRequest portNumber domainName) = do
   eitherP2prcAPI <- getP2prcAPI
 
   case eitherP2prcAPI of
-    (Right p2prcAPI) -> do
+    (Right
+      ( MkP2PRCapi
+        { startServer     = startServer
+        , execInitConfig  = execInitConfig
+        , execListServers = execListServers
+        , execMapPort     = execMapPort
+        }
+      )) -> do
       let
-        ( MkP2PRCapi
-          { startServer     = startServer
-          , execInitConfig  = execInitConfig
-          , execListServers = execListServers
-          , execMapPort     = execMapPort
-          }
-          ) = p2prcAPI
 
 
       configValue <- execInitConfig

haskell/lib/Error.hs

@@ -5,19 +5,24 @@ module Error
   ) where
 
 
--- ^ Error type for the application
+{- |
+  Haskell-side Error value. This type is designed to parse and track System and P2PRC's error signals in a safe and effective manner.
+
+  It does have an 'MkUnknownError' value which is meant to be warn about new kinds of error not yet accounted in this client. Github issues and pull requests are very welcome to improve error handling by parsing more types of errors.
+
+-}
 data Error
-  = MkUnknownError
-      String -- ^ error message
-  | MkErrorSpawningProcess
-      String -- ^ error message
-  | MkSystemError
-      Int -- ^ System error code
-      String -- ^ String1
-      String -- ^ String2
+  = MkCLISystemError        -- ^ This is a CLI System Error
+      Int                     -- ^ System error code
+      String                  -- ^ Command name executed
+      String                  -- ^ Error output
+  | MkErrorSpawningProcess  -- ^ Spawing process error
+      String                  -- ^ Spawning executable name
+  | MkUnknownError          -- ^ This is an unparsed P2PRC's error
+      String                  -- ^ Unparsed error message
   deriving Show
 
--- ^ Type synonym for an IO action with either returns an Error or a parsed value
+-- | Type synonym for an IO action with either returns an Error or a parsed value
 type IOEitherError a = IO ( Either Error a)
 
 assignError :: String -> Error

haskell/lib/JSON.hs

@@ -3,7 +3,7 @@
 module JSON
   ( P2prcConfig
   , IPAdressTable
-  , MapPortResponse
+  , MapPortResponse(..)
   )
   where
 
@@ -15,13 +15,16 @@ import qualified Data.Text as T
 import Data.Aeson
 
 
-newtype MapPortResponse
-  = MkMapPortResponse
-    { ipAddress :: String
-    -- , ipAddress :: IPAddress -- TODO: fix the api output
-    -- , port      :: Int -- TODO: fix the api output
+{-# WARNING MapPortResponse "This newtype is unstable at the moment due to the P2PRC's library error handling bug. For more information visit: https://github.com/Akilan1999/p2p-rendering-computation/issues/114#issuecomment-2474737015" #-}
+
+-- | This record type represents P2PRC's response to the TCP port and DNS address allocation.
+data MapPortResponse
+  = MkMapPortResponse       -- ^ Single data constructor
+    { ipAddress :: String     -- ^ Column separated Host's IP address and Port
     }
   deriving Show
+    -- , ipAddress :: IPAddress -- TODO: fix the api output
+    -- , port      :: Int -- TODO: fix the api output
 
 
 
@@ -30,15 +33,13 @@ instance FromJSON MapPortResponse where
 
     ipAddress <- o .: "IPAddress"
 
-    pure $
-      MkMapPortResponse
-        { ipAddress=ipAddress
-        }
+    pure $ MkMapPortResponse ipAddress
 
   parseJSON _ = mzero
 
 
 
+{-# WARNING P2prcConfig "This type is unstable at the moment due to the P2PRC's library error handling bug. For more information visit: https://github.com/Akilan1999/p2p-rendering-computation/issues/114#issuecomment-2474737015" #-}
 -- | Host P2prc configuration
 newtype P2prcConfig = MkP2prConfig
   { machineName               :: String
@@ -106,6 +107,8 @@ instance FromJSON P2prcConfig where
   parseJSON _ = mzero
 
 
+{-# WARNING IPAdressTable "This newtype is highly unstable due to undergoing work on improving P2PRC's server api. For more information, visit: https://github.com/Akilan1999/p2p-rendering-computation/issues/114" #-}
+
 newtype IPAdressTable
   = MkIPAdressTable [ServerInfo]
   deriving Show

haskell/lib/P2PRC.hs

@@ -56,7 +56,7 @@ module P2PRC
   , IPAdressTable
   , MapPortRequest(..)
   , MapPortResponse
-  , Error
+  , Error(..)
 
     -- ** Type Synonyms
     -- | This section is reserved to some useful type synonyms that add significant ergonomics.
@@ -71,7 +71,7 @@ import Engine
 
 import JSON
   ( IPAdressTable
-  , MapPortResponse
+  , MapPortResponse(..)
   , P2prcConfig
   )
 
@@ -83,7 +83,7 @@ import API
 
 
 import Error
-  ( Error
+  ( Error(..)
   , IOEitherError
   )