From b8df907e76b8ac7cdf59b26f0e75a477d926f122 Mon Sep 17 00:00:00 2001
From: stuebinm
Date: Sun, 21 Jul 2024 17:55:36 +0200
Subject: document publicly exposed interface

this documents most functions that might be used by downstream consumers
of this library, except for those in Conftrack.Pretty, which aren't done
yet.
---
 src/Conftrack/Source/Aeson.hs   | 7 ++++++-
 src/Conftrack/Source/Trivial.hs | 1 +
 src/Conftrack/Source/Yaml.hs    | 1 +
 3 files changed, 8 insertions(+), 1 deletion(-)

(limited to 'src/Conftrack/Source')

diff --git a/src/Conftrack/Source/Aeson.hs b/src/Conftrack/Source/Aeson.hs
index 97353d0..17ea4ee 100644
--- a/src/Conftrack/Source/Aeson.hs
+++ b/src/Conftrack/Source/Aeson.hs
@@ -7,7 +7,8 @@
 {-# LANGUAGE RecordWildCards #-}
 {-# LANGUAGE LambdaCase #-}
 
-module Conftrack.Source.Aeson (JsonSource(..), mkJsonSource, mkJsonSourceWith, mkJsonFileSource) where
+-- | Functions for producing sources reading from json strings or files, using the aeson library.
+module Conftrack.Source.Aeson (mkJsonSource, mkJsonSourceWith, mkJsonFileSource, JsonSource(..)) where
 
 import Conftrack.Value (Key (..), ConfigError(..), Value (..), KeyPart)
 import Conftrack.Source (SomeSource(..), ConfigSource (..))
@@ -37,13 +38,17 @@ data JsonSource = JsonSource
   , jsonSourceDescription :: Text
   } deriving (Show)
 
+-- | Make a source from an aeson value
 mkJsonSource :: A.Value -> SomeSource
 mkJsonSource value = mkJsonSourceWith ("JSON string " <> LT.toStrict (A.encodeToLazyText value)) value
 
+-- | same as 'mkJsonSource', but with an additional description to be shown
+-- in output of 'Conftrack.Pretty.printConfigOrigins'.
 mkJsonSourceWith :: Text -> A.Value -> SomeSource
 mkJsonSourceWith description value = SomeSource (source, [])
   where source = JsonSource value description
 
+-- | Make a source from a json file.
 mkJsonFileSource :: OsPath -> IO (Maybe SomeSource)
 mkJsonFileSource path = do
   bytes <- readFile path
diff --git a/src/Conftrack/Source/Trivial.hs b/src/Conftrack/Source/Trivial.hs
index d4151c2..842ca46 100644
--- a/src/Conftrack/Source/Trivial.hs
+++ b/src/Conftrack/Source/Trivial.hs
@@ -5,6 +5,7 @@
 {-# LANGUAGE AllowAmbiguousTypes #-}
 {-# LANGUAGE OverloadedStrings #-}
 
+-- | A trivial source reading from a @Map Key Value@, only useful as a demonstration or for tests.
 module Conftrack.Source.Trivial where
 
 import Conftrack.Value (Key, Value(..), ConfigError(..))
diff --git a/src/Conftrack/Source/Yaml.hs b/src/Conftrack/Source/Yaml.hs
index 6adc798..4642922 100644
--- a/src/Conftrack/Source/Yaml.hs
+++ b/src/Conftrack/Source/Yaml.hs
@@ -6,6 +6,7 @@
 {-# LANGUAGE OverloadedStrings #-}
 {-# LANGUAGE UndecidableInstances #-}
 
+-- | Functions for producing sources reading from yaml strings or files, using the aeson library.
 module Conftrack.Source.Yaml (YamlSource(..), mkYamlSource, mkYamlSourceWith, mkYamlFileSource) where
 
 import Conftrack.Source (SomeSource(..), ConfigSource (..))
-- 
cgit v1.2.3