Add haddocks

Author: michaelwebb76

README.md

@@ -1,4 +1,97 @@
-# Types for representing Github Actions workflows
+# Github Actions
+
+[![Haskell-CI](https://github.com/bellroy/github-actions/actions/workflows/haskell-ci.yml/badge.svg)](https://github.com/bellroy/github-actions/actions/workflows/haskell-ci.yml)
+
+This library provides types and instances for serializing and deserializing
+GitHub Actions YAML, so that workflows can be built and maintained in Haskell.
 
 As specified here:
 https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions
+
+## Usage Examples
+
+### 1. Exporting a Workflow to YAML
+
+You can create a workflow in Haskell and export it to YAML format:
+
+```haskell
+{-# LANGUAGE OverloadedStrings #-}
+
+import qualified Data.Yaml as YAML
+import qualified Data.Map as Map
+import qualified Data.Set as Set
+import Data.List.NonEmpty (NonEmpty(..))
+import Language.Github.Actions.Workflow
+import qualified Language.Github.Actions.Job as Job
+import qualified Language.Github.Actions.Job.Id as JobId
+import qualified Language.Github.Actions.Step as Step
+import qualified Language.Github.Actions.Workflow.Trigger as Trigger
+
+-- Create a simple CI workflow
+myWorkflow :: Workflow
+myWorkflow = new
+  { workflowName = Just "CI"
+  , on = Set.singleton (Trigger.PushTrigger Trigger.pushTriggerDefaults)
+  , jobs = Map.singleton (JobId.JobId "build") buildJob
+  }
+
+buildJob :: Job.Job
+buildJob = Job.new
+  { Job.jobName = Just "Build and Test"
+  , Job.runsOn = Just "ubuntu-latest"
+  , Job.steps = Just $ checkoutStep :| [buildStep, testStep]
+  }
+
+checkoutStep :: Step.Step
+checkoutStep = Step.new
+  { Step.name = Just "Checkout repository"
+  , Step.uses = Just "actions/checkout@v4"
+  }
+
+buildStep :: Step.Step
+buildStep = Step.new
+  { Step.name = Just "Build project"
+  , Step.run = Just "npm install && npm run build"
+  }
+
+testStep :: Step.Step
+testStep = Step.new
+  { Step.name = Just "Run tests"
+  , Step.run = Just "npm test"
+  }
+
+-- Export to YAML
+exportWorkflow :: IO ()
+exportWorkflow = YAML.encodeFile "workflow.yml" myWorkflow
+```
+
+### 2. Importing a YAML file into a Workflow representation
+
+You can load an existing GitHub Actions YAML file into a Haskell `Workflow` type:
+
+```haskell
+{-# LANGUAGE TypeApplications #-}
+
+import qualified Data.Yaml as YAML
+import Language.Github.Actions.Workflow (Workflow)
+
+-- Import from YAML file
+importWorkflow :: FilePath -> IO (Either String Workflow)
+importWorkflow yamlFilePath = do
+  result <- YAML.decodeFileEither @Workflow yamlFilePath
+  case result of
+    Left parseException ->
+      return $ Left $ YAML.prettyPrintParseException parseException
+    Right workflow ->
+      return $ Right workflow
+
+-- Example usage
+main :: IO ()
+main = do
+  result <- importWorkflow ".github/workflows/ci.yml"
+  case result of
+    Left errorMsg -> putStrLn $ "Failed to parse workflow: " ++ errorMsg
+    Right workflow -> do
+      putStrLn "Successfully parsed workflow!"
+      print workflow
+```

src/Language/Github/Actions/Concurrency.hs

@@ -4,6 +4,21 @@
 {-# LANGUAGE OverloadedStrings #-}
 {-# LANGUAGE RecordWildCards #-}
 
+-- |
+-- Module      : Language.Github.Actions.Concurrency
+-- Description : GitHub Actions concurrency settings
+-- Copyright   : (c) 2025 Bellroy Pty Ltd
+-- License     : BSD-3-Clause
+-- Maintainer  : Bellroy Tech Team <[email protected]>
+--
+-- This module provides the 'Concurrency' type for controlling concurrent execution
+-- of GitHub Actions workflows and jobs.
+--
+-- Concurrency settings allow you to control how many workflow runs or job executions
+-- can happen simultaneously, helping to prevent resource conflicts and manage costs.
+--
+-- For more information about GitHub Actions concurrency, see:
+-- <https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#concurrency>
 module Language.Github.Actions.Concurrency
   ( Concurrency (..),
     gen,
@@ -18,8 +33,30 @@ import Hedgehog (MonadGen)
 import qualified Hedgehog.Gen as Gen
 import qualified Hedgehog.Range as Range
 
+-- | Concurrency settings for workflows and jobs.
+--
+-- Concurrency allows you to control whether multiple workflow runs or job executions
+-- can happen simultaneously. This is useful for preventing conflicts when deploying
+-- or when you want to ensure only one workflow processes a particular resource at a time.
+--
+-- Example usage:
+--
+-- @
+-- import Language.Github.Actions.Concurrency
+--
+-- -- Only allow one deployment per branch
+-- deploymentConcurrency :: Concurrency
+-- deploymentConcurrency = Concurrency
+--  { group = Just "${{ github.ref }}"
+--  , cancelInProgress = Just True
+--  }
+-- @
+--
+-- For more details, see: <https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#concurrency>
 data Concurrency = Concurrency
-  { group :: Maybe Text,
+  { -- | Concurrency group identifier
+    group :: Maybe Text,
+    -- | Whether to cancel in-progress runs
     cancelInProgress :: Maybe Bool
   }
   deriving stock (Eq, Generic, Ord, Show)
@@ -37,6 +74,7 @@ instance ToJSON Concurrency where
         "cancel-in-progress" .= cancelInProgress
       ]
 
+-- | Generate a random 'Concurrency' for property-based testing.
 gen :: (MonadGen m) => m Concurrency
 gen = do
   group <- Gen.maybe (Gen.text (Range.linear 1 5) Gen.alphaNum)

src/Language/Github/Actions/Defaults.hs

@@ -3,6 +3,21 @@
 {-# LANGUAGE OverloadedStrings #-}
 {-# LANGUAGE RecordWildCards #-}
 
+-- |
+-- Module      : Language.Github.Actions.Defaults
+-- Description : Default settings for GitHub Actions workflows and jobs
+-- Copyright   : (c) 2025 Bellroy Pty Ltd
+-- License     : BSD-3-Clause
+-- Maintainer  : Bellroy Tech Team <[email protected]>
+--
+-- This module provides the 'Defaults' type for setting default values that apply
+-- to all steps within a job or all jobs within a workflow.
+--
+-- Defaults allow you to specify common settings like shell type and working directory
+-- that will be inherited by all steps unless explicitly overridden at the step level.
+--
+-- For more information about GitHub Actions defaults, see:
+-- <https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#defaults>
 module Language.Github.Actions.Defaults
   ( Defaults (..),
     gen,
@@ -20,8 +35,39 @@ import qualified Hedgehog.Range as Range
 import Language.Github.Actions.Shell (Shell)
 import qualified Language.Github.Actions.Shell as Shell
 
+-- | Default settings for steps within a job or jobs within a workflow.
+--
+-- Defaults provide a convenient way to set common configuration that applies to
+-- multiple steps without having to repeat the same settings everywhere.
+--
+-- Currently supports defaults for the 'run' command configuration:
+--
+-- Example usage:
+--
+-- @
+-- import Language.Github.Actions.Defaults
+-- import Language.Github.Actions.Shell
+--
+-- -- Set bash as default shell for all steps
+-- bashDefaults :: Defaults
+-- bashDefaults = Defaults
+--  { runShell = Just (Bash Nothing)
+--  , runWorkingDirectory = Nothing
+--  }
+--
+-- -- Set working directory for all steps
+-- workdirDefaults :: Defaults
+-- workdirDefaults = Defaults
+--  { runShell = Nothing
+--  , runWorkingDirectory = Just "\/src"
+--  }
+-- @
+--
+-- For more details, see: <https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#defaults>
 data Defaults = Defaults
-  { runShell :: Maybe Shell,
+  { -- | Default shell for run commands
+    runShell :: Maybe Shell,
+    -- | Default working directory for run commands
     runWorkingDirectory :: Maybe Text
   }
   deriving stock (Eq, Generic, Ord, Show)
@@ -45,6 +91,10 @@ instance ToJSON Defaults where
             )
       ]
 
+-- | Generate a random 'Defaults' for property-based testing.
+--
+-- This generator creates defaults with randomized properties suitable for testing
+-- JSON serialization roundtrips and other property-based tests.
 gen :: (MonadGen m) => m Defaults
 gen = do
   runShell <- Gen.maybe Shell.gen

src/Language/Github/Actions/Internal.hs

@@ -1,32 +1,82 @@
 {-# LANGUAGE ScopedTypeVariables #-}
 {-# LANGUAGE TypeApplications #-}
 
+-- |
+-- Module      : Language.Github.Actions.Internal
+-- Description : Internal utility functions for GitHub Actions library
+-- Copyright   : (c) 2025 Bellroy Pty Ltd
+-- License     : BSD-3-Clause
+-- Maintainer  : Bellroy Tech Team <[email protected]>
+--
+-- This module provides internal utility functions used throughout the GitHub Actions
+-- library. These functions are not intended for external use but are exported for
+-- testing and internal module dependencies.
+--
+-- The main utility is 'inverseMap' which creates bidirectional mappings between
+-- enumeration values and their string representations, commonly used for JSON
+-- serialization of activity types and other enumerated values.
 module Language.Github.Actions.Internal
   ( inverseMap,
   )
 where
 
 import qualified Data.Map as Map
 
--- | https://hackage.haskell.org/package/relude-1.2.2.0/docs/src/Relude.Enum.html#inverseMap
+-- | Create an inverse mapping from keys back to enumeration values.
+--
+-- This function takes a function that converts enumeration values to keys
+-- and returns a function that can look up the original enumeration value
+-- from a key. This is commonly used for parsing JSON representations of
+-- enumeration types.
+--
+-- Example usage:
+--
+-- @
+-- data Color = Red | Green | Blue
+--  deriving (Bounded, Enum, Eq, Ord, Show)
+--
+-- colorToText :: Color -> Text
+-- colorToText Red = "red"
+-- colorToText Green = "green"
+-- colorToText Blue = "blue"
+--
+-- textToColor :: Text -> Maybe Color
+-- textToColor = inverseMap colorToText
+--
+-- -- Usage:
+-- textToColor "red"   == Just Red
+-- textToColor "green" == Just Green
+-- textToColor "blue"  == Just Blue
+-- textToColor "yellow" == Nothing
+-- @
+--
+-- Based on: <https://hackage.haskell.org/package/relude-1.2.2.0/docs/src/Relude.Enum.html#inverseMap>
 inverseMap ::
   forall a k.
   (Bounded a, Enum a, Ord k) =>
+  -- | Function from enumeration values to keys
   (a -> k) ->
+  -- | Function from keys to enumeration values
   (k -> Maybe a)
 inverseMap f = (`Map.lookup` dict)
   where
     dict :: Map.Map k a
     dict = Map.fromList (fmapToFst f (universe @a))
 
--- | https://hackage.haskell.org/package/relude-1.2.2.0/docs/src/Relude.Extra.Tuple.html#fmapToFst
+-- | Map a function over a functor, creating tuples with the result as the first element.
+--
+-- Based on: <https://hackage.haskell.org/package/relude-1.2.2.0/docs/src/Relude.Extra.Tuple.html#fmapToFst>
 fmapToFst :: (Functor f) => (a -> b) -> f a -> f (b, a)
 fmapToFst = fmap . toFst
 
--- | https://hackage.haskell.org/package/relude-1.2.2.0/docs/src/Relude.Enum.html#universe
+-- | Generate all values of a bounded enumeration type.
+--
+-- Based on: <https://hackage.haskell.org/package/relude-1.2.2.0/docs/src/Relude.Enum.html#universe>
 universe :: (Bounded a, Enum a) => [a]
 universe = [minBound .. maxBound]
 
--- | https://hackage.haskell.org/package/relude-1.2.2.0/docs/src/Relude.Extra.Tuple.html#toFst
+-- | Apply a function and create a tuple with the result as the first element.
+--
+-- Based on: <https://hackage.haskell.org/package/relude-1.2.2.0/docs/src/Relude.Extra.Tuple.html#toFst>
 toFst :: (a -> b) -> a -> (b, a)
 toFst f a = (f a, a)