From a3bce80e4ba97a5035cf838ceff8aa38bce6810b Mon Sep 17 00:00:00 2001
From: Florian Hammerschmidt <florianh89@gmail.com>
Date: Thu, 23 Oct 2025 11:32:15 +0200
Subject: [PATCH 1/2] WeakMap docstrings

---
 packages/@rescript/runtime/Stdlib_WeakMap.res | 73 +++++++++++++++++++
 1 file changed, 73 insertions(+)

diff --git a/packages/@rescript/runtime/Stdlib_WeakMap.res b/packages/@rescript/runtime/Stdlib_WeakMap.res
index 9fd4e99c82..403883b8e0 100644
--- a/packages/@rescript/runtime/Stdlib_WeakMap.res
+++ b/packages/@rescript/runtime/Stdlib_WeakMap.res
@@ -1,11 +1,84 @@
+/***
+Bindings to JavaScript's `WeakMap`.
+
+Weak maps keep key/value pairs where keys must be objects and the references do not prevent garbage collection.
+*/
+
+/** Mutable weak map storing values of type `'v` with object keys `'k`. */
 @notUndefined
 type t<'k, 'v>
 
+/**
+Creates an empty weak map.
+
+See [`WeakMap`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap) on MDN.
+
+## Examples
+
+```rescript
+let cache = Stdlib_WeakMap.make()
+Stdlib_WeakMap.get(cache, Stdlib_Object.make()) == None
+```
+*/
 @new external make: unit => t<'k, 'v> = "WeakMap"
 
+/**
+`get(map, key)` returns `Some(value)` when `key` exists, otherwise `None`.
+
+## Examples
+
+```rescript
+let cache = Stdlib_WeakMap.make()
+let key = Stdlib_Object.make()
+Stdlib_WeakMap.get(cache, key) == None
+let _ = Stdlib_WeakMap.set(cache, key, "user")
+Stdlib_WeakMap.get(cache, key) == Some("user")
+```
+*/
 @send external get: (t<'k, 'v>, 'k) => option<'v> = "get"
+
+/**
+`has(map, key)` checks whether `key` exists in the weak map.
+
+## Examples
+
+```rescript
+let cache = Stdlib_WeakMap.make()
+let key = Stdlib_Object.make()
+Stdlib_WeakMap.has(cache, key) == false
+let _ = Stdlib_WeakMap.set(cache, key, ())
+Stdlib_WeakMap.has(cache, key) == true
+```
+*/
 @send external has: (t<'k, 'v>, 'k) => bool = "has"
+
+/**
+`set(map, key, value)` stores `value` for `key` and returns the map for chaining.
+
+## Examples
+
+```rescript
+let cache = Stdlib_WeakMap.make()
+let key = Stdlib_Object.make()
+let _ = Stdlib_WeakMap.set(cache, key, 42)
+Stdlib_WeakMap.get(cache, key) == Some(42)
+```
+*/
 @send external set: (t<'k, 'v>, 'k, 'v) => t<'k, 'v> = "set"
+
+/**
+`delete(map, key)` removes `key` and returns `true` if an entry existed.
+
+## Examples
+
+```rescript
+let cache = Stdlib_WeakMap.make()
+let key = Stdlib_Object.make()
+Stdlib_WeakMap.delete(cache, key) == false
+let _ = Stdlib_WeakMap.set(cache, key, 1)
+Stdlib_WeakMap.delete(cache, key) == true
+```
+*/
 @send external delete: (t<'k, 'v>, 'k) => bool = "delete"
 
 /**

From c180bd35ef4778b9ab4862ba8cb96f60f4d9df52 Mon Sep 17 00:00:00 2001
From: Florian Hammerschmidt <florianh89@gmail.com>
Date: Thu, 23 Oct 2025 13:54:56 +0200
Subject: [PATCH 2/2] MDN links

---
 packages/@rescript/runtime/Stdlib_WeakMap.res | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/packages/@rescript/runtime/Stdlib_WeakMap.res b/packages/@rescript/runtime/Stdlib_WeakMap.res
index 403883b8e0..4ac50a4930 100644
--- a/packages/@rescript/runtime/Stdlib_WeakMap.res
+++ b/packages/@rescript/runtime/Stdlib_WeakMap.res
@@ -25,6 +25,8 @@ Stdlib_WeakMap.get(cache, Stdlib_Object.make()) == None
 /**
 `get(map, key)` returns `Some(value)` when `key` exists, otherwise `None`.
 
+See [`WeakMap.prototype.get`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap/get) on MDN.
+
 ## Examples
 
 ```rescript
@@ -40,6 +42,8 @@ Stdlib_WeakMap.get(cache, key) == Some("user")
 /**
 `has(map, key)` checks whether `key` exists in the weak map.
 
+See [`WeakMap.prototype.has`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap/has) on MDN.
+
 ## Examples
 
 ```rescript
@@ -55,6 +59,8 @@ Stdlib_WeakMap.has(cache, key) == true
 /**
 `set(map, key, value)` stores `value` for `key` and returns the map for chaining.
 
+See [`WeakMap.prototype.set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap/set) on MDN.
+
 ## Examples
 
 ```rescript
@@ -69,6 +75,8 @@ Stdlib_WeakMap.get(cache, key) == Some(42)
 /**
 `delete(map, key)` removes `key` and returns `true` if an entry existed.
 
+See [`WeakMap.prototype.delete`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap/delete) on MDN.
+
 ## Examples
 
 ```rescript