Improve documentation (haskell#74)

* Improve documentation of `Control.Parallel`
* Update changelog
* Update CI
* Fix typo

Co-authored-by: ˌbodʲɪˈɡrʲim <[email protected]>

Author: konsumlamm

.github/workflows/haskell-ci.yml

@@ -8,9 +8,9 @@
 #
 # For more information, see https://github.com/andreasabel/haskell-ci
 #
-# version: 0.19.20241021
+# version: 0.19.20241219
 #
-# REGENDATA ("0.19.20241021",["github","parallel.cabal"])
+# REGENDATA ("0.19.20241219",["github","parallel.cabal"])
 #
 name: Haskell-CI
 on:
@@ -32,19 +32,19 @@ jobs:
     strategy:
       matrix:
         include:
-          - compiler: ghc-9.12.20241014
+          - compiler: ghc-9.12.1
             compilerKind: ghc
-            compilerVersion: 9.12.20241014
+            compilerVersion: 9.12.1
             setup-method: ghcup
             allow-failure: false
           - compiler: ghc-9.10.1
             compilerKind: ghc
             compilerVersion: 9.10.1
             setup-method: ghcup
             allow-failure: false
-          - compiler: ghc-9.8.2
+          - compiler: ghc-9.8.4
             compilerKind: ghc
-            compilerVersion: 9.8.2
+            compilerVersion: 9.8.4
             setup-method: ghcup
             allow-failure: false
           - compiler: ghc-9.6.6
@@ -99,16 +99,30 @@ jobs:
             allow-failure: false
       fail-fast: false
     steps:
-      - name: apt
+      - name: apt-get install
         run: |
           apt-get update
           apt-get install -y --no-install-recommends gnupg ca-certificates dirmngr curl git software-properties-common libtinfo5 libnuma-dev
+      - name: Install GHCup
+        run: |
           mkdir -p "$HOME/.ghcup/bin"
           curl -sL https://downloads.haskell.org/ghcup/0.1.30.0/x86_64-linux-ghcup-0.1.30.0 > "$HOME/.ghcup/bin/ghcup"
           chmod a+x "$HOME/.ghcup/bin/ghcup"
+      - name: Install cabal-install (prerelease)
+        run: |
           "$HOME/.ghcup/bin/ghcup" config add-release-channel https://raw.githubusercontent.com/haskell/ghcup-metadata/master/ghcup-prereleases-0.0.8.yaml;
+          "$HOME/.ghcup/bin/ghcup" install cabal 3.15.0.0.2024.10.3 || (cat "$HOME"/.ghcup/logs/*.* && false)
+          echo "CABAL=$HOME/.ghcup/bin/cabal-3.15.0.0.2024.10.3 -vnormal+nowrap" >> "$GITHUB_ENV"
+      - name: Install GHC (GHCup)
+        if: matrix.setup-method == 'ghcup'
+        run: |
           "$HOME/.ghcup/bin/ghcup" install ghc "$HCVER" || (cat "$HOME"/.ghcup/logs/*.* && false)
-          "$HOME/.ghcup/bin/ghcup" install cabal 3.12.1.0 || (cat "$HOME"/.ghcup/logs/*.* && false)
+          HC=$("$HOME/.ghcup/bin/ghcup" whereis ghc "$HCVER")
+          HCPKG=$(echo "$HC" | sed 's#ghc$#ghc-pkg#')
+          HADDOCK=$(echo "$HC" | sed 's#ghc$#haddock#')
+          echo "HC=$HC" >> "$GITHUB_ENV"
+          echo "HCPKG=$HCPKG" >> "$GITHUB_ENV"
+          echo "HADDOCK=$HADDOCK" >> "$GITHUB_ENV"
         env:
           HCKIND: ${{ matrix.compilerKind }}
           HCNAME: ${{ matrix.compiler }}
@@ -119,21 +133,12 @@ jobs:
           echo "LANG=C.UTF-8" >> "$GITHUB_ENV"
           echo "CABAL_DIR=$HOME/.cabal" >> "$GITHUB_ENV"
           echo "CABAL_CONFIG=$HOME/.cabal/config" >> "$GITHUB_ENV"
-          HCDIR=/opt/$HCKIND/$HCVER
-          HC=$("$HOME/.ghcup/bin/ghcup" whereis ghc "$HCVER")
-          HCPKG=$(echo "$HC" | sed 's#ghc$#ghc-pkg#')
-          HADDOCK=$(echo "$HC" | sed 's#ghc$#haddock#')
-          echo "HC=$HC" >> "$GITHUB_ENV"
-          echo "HCPKG=$HCPKG" >> "$GITHUB_ENV"
-          echo "HADDOCK=$HADDOCK" >> "$GITHUB_ENV"
-          echo "CABAL=$HOME/.ghcup/bin/cabal-3.12.1.0 -vnormal+nowrap" >> "$GITHUB_ENV"
           HCNUMVER=$(${HC} --numeric-version|perl -ne '/^(\d+)\.(\d+)\.(\d+)(\.(\d+))?$/; print(10000 * $1 + 100 * $2 + ($3 == 0 ? $5 != 1 : $3))')
           echo "HCNUMVER=$HCNUMVER" >> "$GITHUB_ENV"
           echo "ARG_TESTS=--enable-tests" >> "$GITHUB_ENV"
           echo "ARG_BENCH=--enable-benchmarks" >> "$GITHUB_ENV"
           if [ $((HCNUMVER >= 91200)) -ne 0 ] ; then echo "HEADHACKAGE=true" >> "$GITHUB_ENV" ; else echo "HEADHACKAGE=false" >> "$GITHUB_ENV" ; fi
           echo "ARG_COMPILER=--$HCKIND --with-compiler=$HC" >> "$GITHUB_ENV"
-          echo "GHCJSARITH=0" >> "$GITHUB_ENV"
         env:
           HCKIND: ${{ matrix.compilerKind }}
           HCNAME: ${{ matrix.compiler }}
@@ -261,8 +266,8 @@ jobs:
           rm -f cabal.project.local
           $CABAL v2-build $ARG_COMPILER --disable-tests --disable-benchmarks all
       - name: save cache
-        uses: actions/cache/save@v4
         if: always()
+        uses: actions/cache/save@v4
         with:
           key: ${{ runner.os }}-${{ matrix.compiler }}-${{ github.sha }}
           path: ~/.cabal/store

Control/Parallel.hs

@@ -27,7 +27,7 @@ module Control.Parallel (
     ) where
 
 #ifdef __GLASGOW_HASKELL__
-import qualified GHC.Conc       ( par, pseq )
+import qualified GHC.Conc (par, pseq)
 
 infixr 0 `par`, `pseq`
 #endif
@@ -38,7 +38,8 @@ infixr 0 `par`, `pseq`
 -- argument in parallel with the second.  Returns the value of the
 -- second argument.
 --
--- @a ``par`` b@ is exactly equivalent semantically to @b@.
+-- The result of @a ``par`` b@ is always  @b@, regardless of whether
+-- @a@ evaluates to a bottom, so for example @par undefined x = x@.
 --
 -- @par@ is generally used when the value of @a@ is likely to be
 -- required later, but not immediately.  Also it is a good idea to
@@ -47,9 +48,8 @@ infixr 0 `par`, `pseq`
 -- running it in parallel.
 --
 -- Note that actual parallelism is only supported by certain
--- implementations (GHC with the @-threaded@ option, and GPH, for
--- now).  On other implementations, @par a b = b@.
---
+-- implementations (GHC with the @-threaded@ option, for now).
+-- On other implementations, @par a b = b@.
 par :: a -> b -> b
 #ifdef __GLASGOW_HASKELL__
 par = GHC.Conc.par
@@ -58,8 +58,13 @@ par = GHC.Conc.par
 par a b = b
 #endif
 
--- | Semantically identical to 'seq', but with a subtle operational
--- difference: 'seq' is strict in both its arguments, so the compiler
+-- | Like 'seq' but ensures that the first argument is evaluated before returning.
+--
+-- @a ``pseq`` b@ evaluates @a@ to weak head normal form (WHNF)
+-- before returning @b@.
+--
+-- This is similar to 'seq', but with a subtle difference:
+-- 'seq' is strict in both its arguments, so the compiler
 -- may, for example, rearrange @a ``seq`` b@ into @b ``seq`` a ``seq`` b@.
 -- This is normally no problem when using 'seq' to express strictness,
 -- but it can be a problem when annotating code for parallelism,
@@ -71,7 +76,6 @@ par a b = b
 -- strict in its first argument (as far as the compiler is concerned),
 -- which restricts the transformations that the compiler can do, and
 -- ensures that the user can retain control of the evaluation order.
---
 pseq :: a -> b -> b
 #ifdef __GLASGOW_HASKELL__
 pseq = GHC.Conc.pseq

changelog.md

@@ -1,41 +1,47 @@
 # Changelog for [`parallel` package](http://hackage.haskell.org/package/parallel)
 
+## 3.3.0.0  *upcoming*
+
+* Bump dependency bounds
+* Make strategic function application operators handle strategies correctly ([#61](https://github.com/haskell/parallel/pull/61))
+* Add `parFmap` ([#53](https://github.com/haskell/parallel/pull/53))
+
 ## 3.2.2.0  *Jul 2018*
 
-  - bump dependency bounds
-  - add parEval
-  - add a MonadFix instance
+* Bump dependency bounds
+* Add `parEval`
+* Add a `MonadFix Eval` instance
 
 ## 3.2.1.1  *Apr 2017*
 
-  - Compatibility with `deepseq-1.4.3`
-  - Minor documentation clarifications
+* Compatibility with `deepseq-1.4.3`
+* Minor documentation clarifications
 
 ## 3.2.1.0  *Jan 2016*
 
-  - Support `base-4.9.0.0`
-  - Add `{-# NOINLINE[1] rseq #-}` to make the `RULE` more robust
-  - Fix broken links to papers in Haddock
-  - Make `rpar` type signature consistent with `rseq` via type-synonym
-  - Drop redundant `Ix`-constraint on `seqArray`/`seqArrayBounds` for GHC >= 8.0
+* Support `base-4.9.0.0`
+* Add `{-# NOINLINE[1] rseq #-}` to make the `RULE` more robust
+* Fix broken links to papers in Haddock
+* Make `rpar` type signature consistent with `rseq` via type synonym
+* Drop redundant `Ix`-constraint on `seqArray`/`seqArrayBounds` for GHC >= 8.0
 
 ## 3.2.0.6  *Dec 2014*
 
-  - Make `-Wall` message free for all supported `base` versions
+* Make `-Wall` message free for all supported `base` versions
 
 ## 3.2.0.5  *Dec 2014*
 
-  - Support `base-4.8.0.0`/`deepseq-1.4.0.0` (and thus GHC 7.10)
+* Support `base-4.8.0.0`/`deepseq-1.4.0.0` (and thus GHC 7.10)
 
 ## 3.2.0.4  *Nov 2013*
 
-  * Update package description to Cabal 1.10 format
-  * Add support for GHC 7.8
-  * Drop support for GHCs older than GHC 7.0.1
-  * Add NOINLINE pragmas to `parBuffer`, `parList`, and `evalBuffer`
-    to make RULEs more likely to fire
+* Update package description to Cabal 1.10 format
+* Add support for GHC 7.8
+* Drop support for GHCs older than GHC 7.0.1
+* Add NOINLINE pragmas to `parBuffer`, `parList`, and `evalBuffer`
+  to make RULEs more likely to fire
 
 ## Older versions
 
-  * This package has a long history which is described in the Haddock documentation
-    in the ["API History" section](./docs/Control-Parallel-Strategies.html#history)
+* This package has a long history which is described in the Haddock documentation
+  in the ["API History" section](./docs/Control-Parallel-Strategies.html#history)

parallel.cabal

@@ -12,9 +12,9 @@ category:       Control, Parallelism
 build-type:     Simple
 
 tested-with:
-  GHC == 9.12.0
+  GHC == 9.12.1
   GHC == 9.10.1
-  GHC == 9.8.2
+  GHC == 9.8.4
   GHC == 9.6.6
   GHC == 9.4.8
   GHC == 9.2.8