From 599444e27e96081ea8a99c62be8bc46bbdff24e6 Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Sat, 8 Mar 2025 23:17:32 +0100
Subject: [PATCH] doc: docstrings for Id (#7204)

This PR adds docstrings for the `Id` monad.
---
 src/Init/Control/Id.lean | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/src/Init/Control/Id.lean b/src/Init/Control/Id.lean
index ab1b4a1a15..50a494095e 100644
--- a/src/Init/Control/Id.lean
+++ b/src/Init/Control/Id.lean
@@ -10,6 +10,28 @@ import Init.Core
 
 universe u
 
+/--
+The identity function on types, used primarily for its `Monad` instance.
+
+The identity monad is useful together with monad transformers to construct monads for particular
+purposes. Additionally, it can be used with `do`-notation in order to use control structures such as
+local mutability, `for`-loops, and early returns in code that does not otherwise use monads.
+
+Examples:
+```lean example
+def containsFive (xs : List Nat) : Bool := Id.run do
+  for x in xs do
+    if x == 5 then return true
+  return false
+```
+
+```lean example
+#eval containsFive [1, 3, 5, 7]
+```
+```output
+true
+```
+-/
 def Id (type : Type u) : Type u := type
 
 namespace Id
@@ -20,9 +42,18 @@ instance : Monad Id where
   bind x f := f x
   map f x := f x
 
+/--
+The identity monad has a `bind` operator.
+-/
 def hasBind : Bind Id :=
   inferInstance
 
+/--
+Runs a computation in the identity monad.
+
+This function is the identity function. Because its parameter has type `Id α`, it causes
+`do`-notation in its arguments to use the `Monad Id` instance.
+-/
 @[always_inline, inline]
 protected def run (x : Id α) : α := x