Minor documentation updates

- OCaml 5.1 is now the minimum version
- Add some helpful links
- Clarify executor pool API docs

Author: SGrondin

README.md

@@ -2,7 +2,7 @@
 
 # Eio -- Effects-Based Parallel IO for OCaml
 
-Eio provides an effects-based direct-style IO stack for OCaml 5.0.
+Eio provides an effects-based direct-style IO stack for OCaml 5.
 For example, you can use Eio to read and write files, make network connections,
 or perform CPU-intensive calculations, running multiple operations at the same time.
 It aims to be easy to use, secure, well documented, and fast.
@@ -17,7 +17,7 @@ Eio replaces existing concurrency libraries such as Lwt
 * [Motivation](#motivation)
 * [Current Status](#current-status)
 * [Structure of the Code](#structure-of-the-code)
-* [Getting OCaml 5.0](#getting-ocaml-50)
+* [Getting OCaml 5.1](#getting-ocaml-51)
 * [Getting Eio](#getting-eio)
 * [Running Eio](#running-eio)
 * [Testing with Mocks](#testing-with-mocks)
@@ -64,10 +64,10 @@ Eio replaces existing concurrency libraries such as Lwt
 ## Motivation
 
 The `Unix` library provided with OCaml uses blocking IO operations, and is not well suited to concurrent programs such as network services or interactive applications.
-For many years, the solution to this has been libraries such as Lwt and Async, which provide a monadic interface.
+For many years, the solution was to use libraries such as Lwt and Async, which provide a monadic interface.
 These libraries allow writing code as if there were multiple threads of execution, each with their own stack, but the stacks are simulated using the heap.
 
-OCaml 5.0 adds support for "effects", removing the need for monadic code here.
+OCaml 5 added support for "effects", removing the need for monadic code here.
 Using effects brings several advantages:
 
 1. It's faster, because no heap allocations are needed to simulate a stack.
@@ -77,17 +77,13 @@ Using effects brings several advantages:
 
 Additionally, modern operating systems provide high-performance alternatives to the old Unix `select` call.
 For example, Linux's io_uring system has applications write the operations they want to perform to a ring buffer,
-which Linux handles asynchronously.
-
-Due to this, many OCaml users will want to rewrite their IO code.
-It would be very beneficial to use this opportunity to standardise a single concurrency API for OCaml,
-and we hope that Eio will be that API.
+which Linux handles asynchronously, and Eio can take advantage of this.
 
 ## Current Status
 
 See [Eio 1.0 progress tracking](https://github.com/ocaml-multicore/eio/issues/388) for the current status.
 Please try porting your programs to use Eio and submit PRs or open issues when you find problems.
-Remember that you can always fall back to using Lwt libraries to provide missing features if necessary.
+Remember that you can always [fall back to using Lwt libraries](#lwt) to provide missing features if necessary.
 
 See [Awesome Multicore OCaml][] for links to work migrating other projects to Eio.
 
@@ -100,19 +96,19 @@ See [Awesome Multicore OCaml][] for links to work migrating other projects to Ei
 - [Eio_windows][] is for use on Windows (incomplete - [help wanted](https://github.com/ocaml-multicore/eio/issues/125)).
 - [Eio_main][] selects an appropriate backend (e.g. `eio_linux` or `eio_posix`), depending on your platform.
 
-## Getting OCaml 5.0
+## Getting OCaml 5.1
 
-You'll need OCaml 5.0.0 or later.
+You'll need OCaml 5.1.0 or later.
 You can either install it yourself or build the included [Dockerfile](./Dockerfile).
 
 To install it yourself:
 
 1. Make sure you have opam 2.1 or later (run `opam --version` to check).
 
-2. Use opam to install OCaml 5.0.0:
+2. Use opam to install OCaml:
 
    ```
-   opam switch create 5.0.0
+   opam switch create 5.1.1
    ```
 
 ## Getting Eio
@@ -1003,7 +999,7 @@ The mock backend provides a mock clock that advances automatically where there i
 
 ## Multicore Support
 
-Fibers are scheduled cooperatively within a single domain, but you can also create new domains that run in parallel.
+Fibers are scheduled cooperatively within a single [domain](https://v2.ocaml.org/manual/parallelism.html), but you can also create new domains that run in parallel.
 This is useful to perform CPU-intensive operations quickly.
 For example, let's say we have a CPU intensive task:
 

lib_eio/executor_pool.mli

@@ -1,9 +1,9 @@
-(** An executor pool distributes jobs among a pool of domains workers (threads).
+(** An executor pool distributes jobs (functions to execute) among a pool of domain workers (threads).
 
     Domains are reused and can execute multiple jobs concurrently.
     Jobs are queued up if they cannot be started immediately due to all workers being busy.
 
-    [Eio.Executor_pool] is the recommended way of leveraging OCaml's 5 multicore capabilities.
+    [Eio.Executor_pool] is the recommended way of leveraging OCaml 5's multicore capabilities.
     It is built on top of the low level [Eio.Domain_manager].
 
     Usually you will only want one pool for an entire application,
@@ -37,7 +37,7 @@ val create :
     The executor pool will not block switch [sw] from completing;
     when the switch finishes, all domain workers and running jobs are cancelled.
 
-    @param domain_count The number of additional domain workers to create.
+    @param domain_count The number of domain workers to create.
                         The total number of domains should not exceed {!Domain.recommended_domain_count} or the number of cores on your system.
                         Additionally, consider reducing this number by 1 if your original domain will be performing CPU intensive work at the same time as the Executor_pool.
 *)