Check grammar of READMES & the CONTRIBUTING.md guide.

Author: coot

CONTRIBUTING.md

@@ -1,12 +1,12 @@
 # Building
 
-The project is build with `cabal-install`.  You might need to run `cabal
+The project is built with `cabal-install`.  You might need to run `cabal
 update` after cloning the repository.
 
 # Design Principles
 
 We designed `io-classes` to be as close as possible to what `base` package
-provides.  Almost all `IO` instances instantiate with api provided by one of
+provides.  Almost all `IO` instances instantiate with API provided by one of
 the core packages, see
 [example](https://github.com/input-output-hk/io-sim/blob/main/io-classes/src/Control/Monad/Class/MonadSTM.hs?plain=1#L410-L446).
 Please keep this in mind when adding new functionality.
@@ -54,13 +54,13 @@ package ouroboros-network-testing
 
 # Code Style
 
-Please follow local style.  For a more detailed style guide see
+Please follow the local style.  For a more detailed style guide see
 [link](https://github.com/input-output-hk/ouroboros-network/blob/master/docs/StyleGuide.md).
 
 # Pull Requests
 
-Each commit shall be small and preferably address one thing at a time.  Well
-organised & documented commits make it much easier for the maintainers to
+Each commit shall be small and preferably address one thing at a time.
+Well-organised & documented commits make it much easier for the maintainers to
 review them.  Hacking sessions are great, but please take your time to organise
 your work, this usually improves the quality too!
 
@@ -75,22 +75,22 @@ Please use a draft PR if the work is still in progress.
 
 We require all commits to be signed, see [this guide][gh-signing-commits].
 
-If your pull requests resolves an existing issue, please link your PR to that
+If your pull requests resolve an existing issue, please link your PR to the
 issue, see [GitHub documentation][gh-link-issue].
 
-Please include your changes in `CHANGELOG.md` files (per package).
+Please include your changes in the `CHANGELOG.md` files (per package).
 
-We prefer to avoid merging commits, rebasing a well organised PR is usually
+We prefer to avoid merging commits, rebasing a well-organised PR is usually
 quite simple.
 
 ## Code Style
 
-Please follow local style.  For a more detailed style guide see
+Please follow the local style.  For a more detailed style guide see
 [link](https://github.com/input-output-hk/ouroboros-network/blob/master/docs/StyleGuide.md).
 
 ## MonadSTM features
 
-If you are adding a new functionality to `MonadSTM`, don't forget to support it
+If you are adding new functionality to `MonadSTM`, don't forget to support it
 in `strict-stm` package.
 
 ## CI
@@ -100,14 +100,14 @@ We run CI using [GitHub actions][ci].
 # Releases
 
 The major version of `io-sim`, `io-classes`, `strict-stm` and `si-timers`
-packages are kept in sync.  This means that if any of the packages introduces
-a breaking change all major version SHOULD be bumped.  The minor versions are
+packages are kept in sync.  This means that if any of the packages introduce
+a breaking change all major versions SHOULD be bumped.  The minor versions are
 kept independent.  The `io-classes-mtl` is still experimental and thus it's not
 following that principle.
 
 The drawback is that if you declare `io-classes ^>= 0.x` then you will need to
-bump it when new version of `io-sim` is published (even if there are no changes
-in `io-classes`).  The con is that you just need to declare version of
+bump it when a new version of `io-sim` is published (even if there are no changes
+in `io-classes`).  The con is that you just need to declare the version of
 `io-classes` to have a consistent ecosystem of the four packages.
 
 # Tips
@@ -116,15 +116,15 @@ in `io-classes`).  The con is that you just need to declare version of
 
 Both `ppTrace` and `ppTrace_` are strict.  They evaluate the trace before they
 produce any result, thus they are not useful when your trace diverges.  This
-can happen if evaluation encounters unhandled exception e.g. one of assertion
+can happen if the evaluation encounters an unhandled exception e.g. an assertion
 fires (either internal or otherwise).  In that case, instead of `ppTrace` you
 can use `Data.Trace.toList` and simply `traverse print` the list.  This will
 give you the trace up to the point of failure.
 
 ## `IOSim` and `STMSim` monads are based on lazy `ST` monad
 
 This means that any action is forced only when the result is needed.  This is
-more lazy than `IO` monad.  Thus if you want to use `Debug.Trace.traceM` inside
+lazier than `IO` monad.  Thus if you want to use `Debug.Trace.traceM` inside
 `schedule` function you need to:
 ```hs
     ...
@@ -138,3 +138,4 @@ more lazy than `IO` monad.  Thus if you want to use `Debug.Trace.traceM` inside
 [gh-link-issue]: https://docs.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue
 [gh-signing-commits]: https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits
 [ci]: https://github.com/input-output-hk/io-sim/actions
+

README.md

@@ -3,46 +3,45 @@
 
 # io-sim
 
-
-`IOSim` is an simulator monad which supports:
+`IOSim` is a simulator monad that supports:
 
 * asynchronous exceptions
 * simulated time
 * timeout API
 * software transaction memory (STM)
-* concurrency: both low level `forkIO` as well as `async` style
+* concurrency: both low-level `forkIO` as well as `async` style
 * strict STM
 * access to lazy ST
 * schedule discovery (see [IOSimPOR][io-sim-por-how-to])
-* eventlog
+* event log
 * dynamic tracing
 * tracing committed changes to `TVar`, `TMVar`s, etc.
-* labelling of threads, `TVar`'s, etc.
+* labeling of threads, `TVar`'s, etc.
 
-`io-classes` provides an interface, which allows to write code which can be run
+`io-classes` provides an interface, which allows writing code that can be run
 in both real `IO` and `IOSim`.  It is a drop-in replacement for `IO`, and
-supports interfaces commonly known from `base`, `exceptions`, `stm`, `async` or
-`time` packages.
+supports interfaces commonly known from `base`, `exceptions`, `stm`, `async`,
+or `time` packages.
 
 One of the principles of `io-classes` was to stay as close to `IO` as possible,
-thus most of the `IO` instances are directly referring to `base` or `async` api.
-However we made some distinctions, which are reported below.
+thus most of the `IO` instances are directly referring to `base` or `async`
+API.  However, we made some distinctions, which are reported below.
 
-`io-classes` supports a novel hierarchy for error handling monads as well more
-familiar `exception` style.  The new hierarchy provides `bracket` and
+`io-classes` supports a novel hierarchy for error-handling monads as well as
+more familiar `exception` style.  The new hierarchy provides `bracket` and
 `finally` functions in the `MonadThrow` class, while `catch` style operators
 are provided by a super-class `MonadCatch`.  Both `bracket` and `finally` are
 the most common functions used to write code with robust exception handling,
 exposing them through the more basic `MonadThrow` class informs the reader
 / reviewer that no tricky error handling is done in that section of the code
 base.
 
-`IOSim` exposes a detailed trace, which can be enhanced by labelling threads,
-or mutable variables, tracing `Dynamic` values (which can be recovered from the
-trace) or simple `String` based tracing.  Although its agnostic with respect to
+`IOSim` exposes a detailed trace, which can be enhanced by labeling threads, or
+mutable variables, tracing `Dynamic` values (which can be recovered from the
+trace), or simple `String` based tracing.  Although it's agnostic concerning
 the logging framework, it worked for us particularly well using
-[contra-tracer][contra-tracer].  It has been used to develop, test and debug
-a complex, highly-concurrent, distributed system
+[contra-tracer][contra-tracer].  It has been used to develop, test, and debug
+a complex, highly concurrent, distributed system
 ([ouroboros-network][ouroboros-network]), in particular
 
 * write network simulations, to verify a complex networking stack;
@@ -61,10 +60,10 @@ a complex, highly-concurrent, distributed system
 * `io-classes`: class bases interface, which allows to to abstract over the
     monad
 * `strict-stm`: strict STM operations
-* `si-timers`: non standard timers API
+* `si-timers`: non-standard timers API
 
 
-## Differences from `base`, `async` or `exceptions` packages
+## Differences from `base`, `async`, or `exceptions` packages
 
 ### Major differences
 
@@ -83,11 +82,11 @@ type Async :: (Type -> Type) -> Type -> Type
 ```
 
 The first type of kind `Type -> Type` describes the monad which could be
-instantiated to `IO`, `IOSim` or some other monad stack build with monad
+instantiated to `IO`, `IOSim` or some other monad stacks built with monad
 transformers.  The same applies to many other types, e.g. `TVar`, `TMVar`.
 
 The following types although similar to the originals are not the same as the
-ones that come from `base`, `async`, or `excpetions` packages:
+ones that come from `base`, `async`, or `exceptions` packages:
 
 * `Handler` (origin: `base`)
 * `MaskingState` (origin: `base`)

io-classes-mtl/README.md

@@ -2,16 +2,16 @@
 
 `ReaderT` instances are included in `io-classes`, but all other instances are
 included in this package.  Some of them are rather novel and experimental
-others might be less so.   This code is not really tested, neither it has run
-in production environment as we know (let us know if you do!).
+others might be less so.   This code is not well tested, and some of it hasn't run
+in a production environment as we know (let us know if you do!).
 
 The `MonadSTM` instances for monad transformers are somewhat novel.  The `STM`
 monad is transformed together with the base monad.  This means that the
-transfomer primitive operations are available in `STM`.  For example you an
+transformer primitive operations are available in `STM`.  For example you an
 `STM` transaction can lock updating the state of the current thread.
 
 We haven't included `MonadAsync` instances (although we have an experimental
-branch how  this could be done).  It could work like the `lifted-async`
+branch how this could be done).  It could work like the `lifted-async`
 package.  But we feel this can be controversial, so it's not included.
 
 The design goal is to follow  `exception` package instances, but since we don't

io-classes/README.md

@@ -1,74 +1,72 @@
 # IO Monad Class Hierarchy
 
-This package provides a monad class hierarchy which is an interface for both the
-[`io-sim`] and [`IO`] monads.  It was developed with the following constraints
-in mind:
+This package provides a monad class hierarchy which is an interface for both
+the [`io-sim`] and [`IO`] monads.  It was developed with the following
+constraints in mind:
 
-* be a drop in replacement for `IO` monad;
+* be a drop-in replacement for `IO` monad;
 * `IO` instances do not alter its original semantics, providing a shallow
-  bindings to [`async`], [`base`], [`stm`] and [`exceptions`] packages as well
-  as timer api;
-* provide zero cost abstractions.
+  bindings to [`async`], [`base`], [`stm`], and [`exceptions`] packages as well
+  as timer API;
+* provide zero-cost abstractions.
 
-We provde also non standard extensions of this api:
+We provide also non-standard extensions of this API:
 
 * [`strict-stm`]: strict `TVar`'s, and other mutable `STM` variables, with
-  suport of the [`nothunks`] library;
+  support of the [`nothunks`] library;
 * [`si-timers`]: timers api:
     - 32-bit safe API using `DiffTime` measured in seconds (rather than time in
       microseconds represented as `Int` as in `base`)
-    - cancellble timeouts.
+    - cancellable timeouts.
 
-[`strict-stm`] and [`nothunks`] were successfuly used in large code base to
+[`strict-stm`] and [`nothunks`] were successfully used in a large code base to
 eliminate space leaks and keep that property over long development cycles.
 
 ## Exception Class Hierarchy
 
 This package provides an alternative class hierarchy giving access to
-exceptions api.  The [`exception`] package class hierarchy is also supported by
+exceptions API.  The [`exception`] package class hierarchy is also supported by
 [`io-sim`], so you can also use either one.
 
-The `MonadThrow` defined in this package allows to work with exceptions without
+The `MonadThrow` defined in this package allows working with exceptions without
 having explicit access to `catch` or `mask`.  It only provides access to
-`throwIO`, `bracket`, `bracket_` and `finally`.  `MonadCatch` class provides
-api which allows to work with exceptions, e.g. `catch` or `bracketOnError`, and
-`MonadMask` gives access to low level `mask` and friends.   This division makes
+`throwIO`, `bracket`, `bracket_`, and `finally`.  `MonadCatch` class provides
+API which allows working with exceptions, e.g. `catch` or `bracketOnError`, and
+`MonadMask` gives access to low-level `mask` and friends.   This division makes
 code review process somewhat easier.  Using only `MonadThrow` constraint, the
-reviewer can be sure that no low level exception api is used, which usually
-requires more care.  Still `MonadThrow` is general enough to to do resource
+reviewer can be sure that no low-level exception API is used, which usually
+requires more care.  Still `MonadThrow` is general enough to do resource
 handling right.
 
 ## Time and Timer APIs
 
 The time and timer APIs of this package follows closely the API exposed by
-[`base`] and [`time`] packages.  We separately packaged a more conveneint API
-in [`si-timers`] (ref [SI]), which provides monoidal action of `DiffTime` on
+[`base`] and [`time`] packages.  We separately packaged a more convenient API
+in [`si-timers`] (ref [SI]), which provides a monoidal action of `DiffTime` on
 monotonic time as well as exposes 32-bit safe timer API (on 32-bit systems time
-in microseconds represented as an `Int` can only holds timeouts of ~35
-minutes).
+in microseconds represented as an `Int` can only hold timeouts of ~35 minutes).
 
-`Control.Monad.Class.MonadTimer.NonStandard.MonadTimeout` provides a low level
-timeout abstraction.  On systems which support native timer manager it's used
-to implement its API, which is very efficient even for low latency timeouts.
+`Control.Monad.Class.MonadTimer.NonStandard.MonadTimeout` provides a low-level
+timeout abstraction.  On systems that support a native timer manager, it's used
+to implement its API, which is very efficient even for low-latency timeouts.
 On other platforms (e.g. `Windows`), it's good enough for subsecond timeouts
-but it's not good enough for fine grained timeouts (e.g. sub milliseconds) as
-it relays on GHC thread scheduler.  We support `MonadTimeout` on `Linux`,
-`MacOS`, `Windows` and `IOSim` (and unofficially on `GHCJS`).
+but it's not good enough for fine-grained timeouts (e.g. sub milliseconds) as
+it relays on the GHC thread scheduler.  We support `MonadTimeout` on `Linux`,
+`MacOS`, `Windows`, and `IOSim` (and unofficially on `GHCJS`).
 
-`MonadDelay` and `MonadTimer` classes provide the well established interface to
+`MonadDelay` and `MonadTimer` classes provide a well-established interface to
 delays & timers.
 
 
 ## Software Transactional Memory API
 
-We provide two interfaces to `stm` api: lazy, included in `io-classes`; and
+We provide two interfaces to `stm` API: lazy, included in `io-classes`; and
 strict one provided by [`strict-stm`].
 
 
 ## Threads API
 
-We draw a line between `base` api and `async` api.  The former one is provided
-by
+We draw a line between `base` API and `async` API.  The former is provided by
 [MonadFork](https://hackage.haskell.org/package/io-classes/docs/Control-Monad-Class-MonadFork.html#t:MonadFork)
 the latter by
 [MonadAsync](https://hackage.haskell.org/package/io-classes/docs/Control-Monad-Class-MonadFork.html#t:MonadAsync).
@@ -78,33 +76,30 @@ packages.
 
 ## Some other APIs
 
-* [MonadEventlog](https://hackage.haskell.org/package/io-sim-classes/docs/Control-Monad-Class-MonadEventlog.html#t:MonadEventlog):
-  provides an API to the
-  [Debug.Trace](https://hackage.haskell.org/package/base/docs/Debug-Trace.html)
-  eventlog interface.
-* [MonadST](https://hackage.haskell.org/package/io-classes/docs/Control-Monad-Class-MonadST.html#t:MonadST): provides a way to lift `ST`-computations.
-* [MonadSay](https://hackage.haskell.org/package/io-classes/docs/Control-Monad-Class-MonadSay.html#t:MonadSay): dummy debugging interface
+* [MonadEventlog]: provides an API to the [Debug.Trace] event log interface.
+* [MonadST]: provides a way to lift `ST`-computations.
+* [MonadSay]: dummy debugging interface
 
 
 ## Debuging & Insepction
 
-We provide quite extended debuging & insepction api.  This proved to be
+We provide quite extended debugging & inspection API.  This proved to be
 extremely helpful when analysing complex deadlocks or livelocks or writing
 complex quickcheck properties of a highly concurrent system.  Some of this is
-only possible because we can control execution environment of [`io-sim`].
+only possible because we can control the execution environment of [`io-sim`].
 
 * `labelThread` as part of `MonadThread` ([`IO`], [`io-sim`], which is also
   part of `GHC` API, ref [`labelThread`][labelThread-base]);
-* `MonadLabelledSTM` which allows to label various `STM` mutable variables,
+* `MonadLabelledSTM` which allows to label of various `STM` mutable variables,
   e.g. `TVar`, `MVar`, etc. ([`io-sim`], not provided by `GHC`);
-* `MonadInspectSTM` which allows to inspect values of `STM` mutable variables
-  when they are commited. ([`io-sim`], not provided by `GHC`).
+* `MonadInspectSTM` which allows inspecting values of `STM` mutable variables
+  when they are committed. ([`io-sim`], not provided by `GHC`).
 
 
-## Monad transformers
+## Monad Transformers
 
 We provide support for monad transformers (although at this stage it might have
-its limitations and so there might be some rought edges.  PRs are welcomed,
+its limitations and so there might be some rough edges.  PRs are welcomed,
 [contributing]).
 
 [SI]: https://www.wikiwand.com/en/International_System_of_Units 
@@ -122,3 +117,8 @@ its limitations and so there might be some rought edges.  PRs are welcomed,
 [contributing]: https://www.github.com/input-output-hk/io-sim/tree/master/CONTRIBUTING.md
 [`nothunks`]: https://hackage.haskell.org/package/nothunks
 [labelThread-base]: https://hackage.haskell.org/package/base-4.17.0.0/docs/GHC-Conc-Sync.html#v:labelThread
+
+[MonadEventlog]: https://hackage.haskell.org/package/io-sim-classes/docs/Control-Monad-Class-MonadEventlog.html#t:MonadEventlog
+[Debug.Trace]: https://hackage.haskell.org/package/base/docs/Debug-Trace.html
+[MonadST]: https://hackage.haskell.org/package/io-classes/docs/Control-Monad-Class-MonadST.html#t:MonadST
+[MonadSay]: https://hackage.haskell.org/package/io-classes/docs/Control-Monad-Class-MonadSay.html#t:MonadSay