From 35b933a2e0fca76c219cef2a8646f106b3b7a4ab Mon Sep 17 00:00:00 2001
From: Michael Lange <dingoeatingfuzz@gmail.com>
Date: Wed, 17 Oct 2018 08:10:16 -0700
Subject: [PATCH] Add more documentation to the format-duration util

---
 ui/app/utils/format-duration.js | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/ui/app/utils/format-duration.js b/ui/app/utils/format-duration.js
index a7f2da486..11856bf44 100644
--- a/ui/app/utils/format-duration.js
+++ b/ui/app/utils/format-duration.js
@@ -1,5 +1,13 @@
 import moment from 'moment';
 
+/**
+ * Metadata for all unit types
+ * name: identifier for the unit. Also maps to moment methods when applicable
+ * suffix: the preferred suffix for a unit
+ * inMoment: whether or not moment can be used to compute this unit value
+ * pluralizable: whether or not this suffix can be pluralized
+ * longSuffix: the suffix to use instead of suffix when longForm is true
+ */
 const allUnits = [
   { name: 'years', suffix: 'year', inMoment: true, pluralizable: true },
   { name: 'months', suffix: 'month', inMoment: true, pluralizable: true },
@@ -14,15 +22,30 @@ const allUnits = [
 
 const pluralizeUnits = (amount, unit, longForm) => {
   let suffix;
+
   if (longForm && unit.longSuffix) {
+    // Long form means always using full words (seconds insteand of s) which means
+    // pluralization is necessary.
     suffix = amount === 1 ? unit.longSuffix : unit.longSuffix.pluralize();
   } else {
+    // In the normal case, only pluralize based on the pluralizable flag
     suffix = amount === 1 || !unit.pluralizable ? unit.suffix : unit.suffix.pluralize();
   }
+
+  // A space should go between the value and the unit when the unit is a full word
+  // 300ns vs. 1 hour
   const addSpace = unit.pluralizable || (longForm && unit.longSuffix);
   return `${amount}${addSpace ? ' ' : ''}${suffix}`;
 };
 
+/**
+ * Format a Duration at a preferred precision
+ *
+ * @param {Number} duration The duration to format
+ * @param {String} units The units for the duration. Default to nanoseconds.
+ * @param {Boolean} longForm Whether or not to expand single character suffixes,
+ *   used to ensure screen readers correctly read units.
+ */
 export default function formatDuration(duration = 0, units = 'ns', longForm = false) {
   const durationParts = {};