From 296e2ef90f7ce5b9c10a8f5e98159b241d799be9 Mon Sep 17 00:00:00 2001
From: yusheng chen <55658154+samuel871211@users.noreply.github.com>
Date: Thu, 3 Apr 2025 22:48:54 +0800
Subject: [PATCH] doc: add JSDoc to file `format.ts` (#17426)

---
 web/utils/format.ts | 45 ++++++++++++++++++++++++++++-----------------
 1 file changed, 28 insertions(+), 17 deletions(-)

diff --git a/web/utils/format.ts b/web/utils/format.ts
index 45f0e51878..720c8f6762 100644
--- a/web/utils/format.ts
+++ b/web/utils/format.ts
@@ -1,8 +1,8 @@
-/*
-* Formats a number with comma separators.
- formatNumber(1234567) will return '1,234,567'
- formatNumber(1234567.89) will return '1,234,567.89'
-*/
+/**
+ * Formats a number with comma separators.
+ * @example formatNumber(1234567) will return '1,234,567'
+ * @example formatNumber(1234567.89) will return '1,234,567.89'
+ */
 export const formatNumber = (num: number | string) => {
   if (!num)
     return num
@@ -11,28 +11,39 @@ export const formatNumber = (num: number | string) => {
   return parts.join('.')
 }
 
-export const formatFileSize = (num: number) => {
-  if (!num)
-    return num
+/**
+ * Format file size into standard string format.
+ * @param fileSize file size (Byte)
+ * @example formatFileSize(1024) will return '1.00KB'
+ * @example formatFileSize(1024 * 1024) will return '1.00MB'
+ */
+export const formatFileSize = (fileSize: number) => {
+  if (!fileSize)
+    return fileSize
   const units = ['', 'K', 'M', 'G', 'T', 'P']
   let index = 0
-  while (num >= 1024 && index < units.length) {
-    num = num / 1024
+  while (fileSize >= 1024 && index < units.length) {
+    fileSize = fileSize / 1024
     index++
   }
-  return `${num.toFixed(2)}${units[index]}B`
+  return `${fileSize.toFixed(2)}${units[index]}B`
 }
 
-export const formatTime = (num: number) => {
-  if (!num)
-    return num
+/**
+ * Format time into standard string format.
+ * @example formatTime(60) will return '1.00 min'
+ * @example formatTime(60 * 60) will return '1.00 h'
+ */
+export const formatTime = (seconds: number) => {
+  if (!seconds)
+    return seconds
   const units = ['sec', 'min', 'h']
   let index = 0
-  while (num >= 60 && index < units.length) {
-    num = num / 60
+  while (seconds >= 60 && index < units.length) {
+    seconds = seconds / 60
     index++
   }
-  return `${num.toFixed(2)} ${units[index]}`
+  return `${seconds.toFixed(2)} ${units[index]}`
 }
 
 export const downloadFile = ({ data, fileName }: { data: Blob; fileName: string }) => {