From 063f781b2f79aaa9f07f8f0a0b4be9b67c4f447b Mon Sep 17 00:00:00 2001
From: Max Duval <hi@mxdvl.com>
Date: Mon, 27 Nov 2023 19:44:11 +0000
Subject: [PATCH] feat(rails-status): add JSDoc (#679)

---
 src/rails-status.js | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/src/rails-status.js b/src/rails-status.js
index 45b66fb5d..0bde425d9 100644
--- a/src/rails-status.js
+++ b/src/rails-status.js
@@ -1,3 +1,4 @@
+/** Status order: later elements have higher precedence. */
 const statusOrder = [
   'deprecated',
   'experimental',
@@ -6,6 +7,12 @@ const statusOrder = [
   'stable'
 ]
 
+/**
+ * Get the latest status, based on the order of precedence
+ * 
+ * @param {readonly string[]} statuses list of status to pick from
+ * @returns {string | null} latest status if valid, `null` otherwise
+ */
 export const latestStatusFrom = (statuses) => {
   let highestRank = -1
   let latestStatus = null
@@ -22,6 +29,13 @@ export const latestStatusFrom = (statuses) => {
   return latestStatus
 }
 
+/**
+ * Compare function, which is compatible with #Array.sort.
+ * 
+ * @param {string} first
+ * @param {string} second
+ * @returns {1 | 0 | -1} sorting order
+ */
 export const compareStatuses = (first, second) => {
   const firstRank = statusOrder.indexOf(first)
   const secondRank = statusOrder.indexOf(second)