docs: Write docs for Reader and Writer (#264)

src/reader.ts

@@ -1,3 +1,33 @@
+/**
+ * This package provides methods for a computation which allows reading external records.
+ *
+ * A {@link Reader.Reader | `Reader<R, A>`} object represents a computation, reading `R` and returning `A`:
+ *
+ * ```ts
+ * type Reader<R, A> = (record: R) => A;
+ * // Note that the actual code is defined as a special case of `ReaderT`.
+ * ```
+ *
+ * And you can work with it by the following methods:
+ *
+ * - {@link Reader.withReader | `withReader`} - Constructs a new {@link Reader.Reader | `Reader`}  from your computation.
+ * - {@link Reader.ask | `ask`} - Makes a pure computation reading the record.
+ * - {@link Reader.compose | `compose`} - Composes two {@link Reader.Reader | `Reader`}s.
+ * - {@link Reader.local | `local`} - Localizes record to be read.
+ * - {@link Reader.run | `run`} - Runs a computation with specified records.
+ * - {@link Reader.weaken | `weaken`} - Makes the record type weaker for application.
+ * - Monad operations:
+ *   - {@link Reader.pure | `pure`} - Wraps a value into a {@link Reader.Reader | `Reader`}.
+ *   - {@link Reader.map | `map`} - Transforms the resulting value of {@link Reader.Reader | `Reader`}.
+ *   - {@link Reader.apply | `apply`} - Applies a {@link Reader.Reader | `Reader`} which results a function into another one.
+ *   - {@link Reader.flatMap | `flatMap`} - Applies a function which returns {@link Reader.Reader | `Reader`} for the resulting value of {@link Reader.Reader | `Reader`}.
+ *
+ * Moreover a {@link Reader.ReaderT | `ReaderT<R, M, A>`} monad transformer is the generalized version of {@link Reader.Reader | `Reader<R, A>`}. It accepts not `A`, but object on monad `M`.
+ *
+ * @packageDocumentation
+ * @module
+ */
+
 import type { Apply2Only, Apply3Only, Get1, Hkt2, Hkt3 } from "./hkt.ts";
 import { type IdentityHkt, monad as identityMonad } from "./identity.ts";
 import type { Tuple } from "./tuple.ts";

src/writer.ts

@@ -1,3 +1,29 @@
+/**
+ * This package provides methods for a computation which allows writing into external records.
+ *
+ * A {@link Writer.Writer | `Writer<W, A>`} object represents a computation, returning `A` and writing `W` out:
+ *
+ * ```ts
+ * type Writer<W, A> = () => [returned: A, written: W];
+ * // Note that the actual code is defined as a special case of `WriterT`.
+ * ```
+ *
+ * And you can work with it by the following methods:
+ *
+ * - {@link Writer.censor | `censor`} - Censors and transforms data to be written.
+ * - {@link Writer.listen | `listen`} - Listens the written record.
+ * - {@link Writer.pass | `pass`} - Applies the function returned from a {@link Writer.Writer | `Writer`} to a record.
+ * - {@link Writer.tell | `tell`} - Writes data as a record.
+ * - {@link Writer.evaluateWriter | `evaluateWriter`} - Runs a {@link Writer.Writer | `Writer`} and gets only the result.
+ * - {@link Writer.executeWriter | `executeWriter`} - Runs a {@link Writer.Writer | `Writer`} and gets only the written record.
+ * - {@link Writer.mapWriter | `mapWriter`} - Transforms output and record of a {@link Writer.Writer | `Writer`}.
+ *
+ * Moreover a {@link Writer.WriterT | `WriterT<R, M, A>`} monad transformer is the generalized version of {@link Writer.Writer | `Writer<R, A>`}. It returns not `A`, but object on monad `M`.
+ *
+ * @packageDocumentation
+ * @module
+ */
+
 import type { Apply2Only, Get1, Hkt2, Hkt3 } from "./hkt.ts";
 import type { IdentityHkt } from "./identity.ts";
 import type { Tuple } from "./tuple.ts";