From ce7ca8868dbad4babba9e536a5ef5804ffa9581d Mon Sep 17 00:00:00 2001
From: Florian Hammerschmidt <florianh89@gmail.com>
Date: Wed, 22 Oct 2025 18:21:06 +0200
Subject: [PATCH] Ordering docstrings

---
 .../@rescript/runtime/Stdlib_Ordering.res     | 85 +++++++++++++++++++
 1 file changed, 85 insertions(+)

diff --git a/packages/@rescript/runtime/Stdlib_Ordering.res b/packages/@rescript/runtime/Stdlib_Ordering.res
index e6a871d29e..f1755b3dc9 100644
--- a/packages/@rescript/runtime/Stdlib_Ordering.res
+++ b/packages/@rescript/runtime/Stdlib_Ordering.res
@@ -1,15 +1,100 @@
+/**
+Ordering values represent the result of a comparison: `less`, `equal`, or `greater`.
+*/
 type t = float
 
+/**
+`less` is the ordering value returned when the left operand is smaller than the right operand.
+
+## Examples
+
+```rescript
+(1)->Int.compare(2) == Ordering.less
+```
+*/
 @inline let less = -1.
+
+/**
+`equal` is the ordering value returned when two values compare the same.
+
+## Examples
+
+```rescript
+(2)->Int.compare(2) == Ordering.equal
+```
+*/
 @inline let equal = 0.
+
+/**
+`greater` is the ordering value returned when the left operand is larger than the right operand.
+
+## Examples
+
+```rescript
+(3)->Int.compare(2) == Ordering.greater
+```
+*/
 @inline let greater = 1.
 
+/**
+`isLess(ordering)` returns `true` when `ordering` equals `Ordering.less`.
+
+## Examples
+
+```rescript
+Ordering.isLess(Ordering.less) == true
+Ordering.isLess(Ordering.equal) == false
+```
+*/
 let isLess = ord => ord < equal
+
+/**
+`isEqual(ordering)` returns `true` when `ordering` equals `Ordering.equal`.
+
+## Examples
+
+```rescript
+Ordering.isEqual(Ordering.equal) == true
+Ordering.isEqual(Ordering.greater) == false
+```
+*/
 let isEqual = ord => ord == equal
+
+/**
+`isGreater(ordering)` returns `true` when `ordering` equals `Ordering.greater`.
+
+## Examples
+
+```rescript
+Ordering.isGreater(Ordering.greater) == true
+Ordering.isGreater(Ordering.less) == false
+```
+*/
 let isGreater = ord => ord > equal
 
+/**
+`invert(ordering)` flips the ordering result (less becomes greater and vice versa).
+
+## Examples
+
+```rescript
+Ordering.invert(Ordering.less) == Ordering.greater
+Ordering.invert(Ordering.equal) == Ordering.equal
+```
+*/
 let invert = ord => -.ord
 
+/**
+`fromInt(n)` converts an integer comparison result into an ordering.
+
+## Examples
+
+```rescript
+Ordering.fromInt(-5) == Ordering.less
+Ordering.fromInt(0) == Ordering.equal
+Ordering.fromInt(3) == Ordering.greater
+```
+*/
 let fromInt = n => n < 0 ? less : n > 0 ? greater : equal
 
 /**