From a972e8270aa071c393c52159a559bd2f995a8752 Mon Sep 17 00:00:00 2001
From: Ethan Zhou <149743008+Aybrea@users.noreply.github.com>
Date: Sun, 3 Nov 2024 18:43:19 +0800
Subject: [PATCH] docs: add json docs (#20)

* fix: unify zh docs subtitle

* docs: add json docs
---
 docs/.vitepress/items/util.ts           |  2 ++
 docs/util/pretty-JSON-object.md         | 33 +++++++++++++++++++++++++
 docs/util/try-parse-JSON.md             | 29 ++++++++++++++++++++++
 docs/zh/collection/merge-with.md        |  2 +-
 docs/zh/collection/merge.md             |  2 +-
 docs/zh/file/to-array-buffer.md         |  2 +-
 docs/zh/file/to-data-url.md             |  2 +-
 docs/zh/file/to-text.md                 |  2 +-
 docs/zh/util/cancel-animation-frame.md  |  2 +-
 docs/zh/util/classes.md                 |  2 +-
 docs/zh/util/create-namespace-fn.md     |  2 +-
 docs/zh/util/double-raf.md              |  2 +-
 docs/zh/util/get-all-parent-scroller.md |  2 +-
 docs/zh/util/get-parent-scroller.md     |  2 +-
 docs/zh/util/get-rect.md                |  2 +-
 docs/zh/util/get-scroll-left.md         |  2 +-
 docs/zh/util/get-scroll-top.md          |  2 +-
 docs/zh/util/get-style.md               |  2 +-
 docs/zh/util/in-viewport.md             |  2 +-
 docs/zh/util/mitt.md                    |  2 +-
 docs/zh/util/pretty-JSON-object.md      | 33 +++++++++++++++++++++++++
 docs/zh/util/prevent-default.md         |  2 +-
 docs/zh/util/raf.md                     |  2 +-
 docs/zh/util/request-animation-frame.md |  2 +-
 docs/zh/util/try-parse-JSON.md          | 29 ++++++++++++++++++++++
 25 files changed, 146 insertions(+), 20 deletions(-)
 create mode 100644 docs/util/pretty-JSON-object.md
 create mode 100644 docs/util/try-parse-JSON.md
 create mode 100644 docs/zh/util/pretty-JSON-object.md
 create mode 100644 docs/zh/util/try-parse-JSON.md

diff --git a/docs/.vitepress/items/util.ts b/docs/.vitepress/items/util.ts
index 6474e24..2dda5e4 100644
--- a/docs/.vitepress/items/util.ts
+++ b/docs/.vitepress/items/util.ts
@@ -14,4 +14,6 @@ export const utilItems = [
   { text: 'getScrollLeft', link: '/util/get-scroll-left' },
   { text: 'getParentScroller', link: '/util/get-parent-scroller' },
   { text: 'getAllParentScroller', link: '/util/get-all-parent-scroller' },
+  { text: 'prettyJSONObject', link: '/util/pretty-JSON-object' },
+  { text: 'tryParseJSON', link: '/util/try-parse-JSON' },
 ]
diff --git a/docs/util/pretty-JSON-object.md b/docs/util/pretty-JSON-object.md
new file mode 100644
index 0000000..703212b
--- /dev/null
+++ b/docs/util/pretty-JSON-object.md
@@ -0,0 +1,33 @@
+# prettyJSONObject
+
+Formats a `JSON` object with indentation for easy readability.
+
+### Usage
+
+```ts
+import { prettyJSONObject } from 'rattail'
+
+const jsonObject = { key: 'value', nested: { key: 'nestedValue' } }
+const pretty = prettyJSONObject(jsonObject)
+console.log(pretty)
+/*
+{
+  "key": "value",
+  "nested": {
+    "key": "nestedValue"
+  }
+}
+*/
+```
+
+### Arguments
+
+| Arg          | Type     | Defaults |
+| ------------ | -------- | -------- |
+| `jsonObject` | `object` |          |
+
+### Return
+
+| Type     |
+| -------- |
+| `string` |
diff --git a/docs/util/try-parse-JSON.md b/docs/util/try-parse-JSON.md
new file mode 100644
index 0000000..359d77d
--- /dev/null
+++ b/docs/util/try-parse-JSON.md
@@ -0,0 +1,29 @@
+# tryParseJSON
+
+Attempts to parse a `JSON` string. If parsing fails, returns `undefined`.
+
+### Usage
+
+```ts
+import { tryParseJSON } from 'rattail'
+
+const jsonString = '{"key": "value"}'
+const parsed = tryParseJSON(jsonString)
+console.log(parsed) // { key: "value" }
+
+const invalidJsonString = '{"key": value}'
+const invalidParsed = tryParseJSON(invalidJsonString)
+console.log(invalidParsed) // undefined
+```
+
+### Arguments
+
+| Arg    | Type     | Defaults |
+| ------ | -------- | -------- |
+| `json` | `string` |          |
+
+### Return
+
+| Type                  |
+| --------------------- |
+| `object \| undefined` |
diff --git a/docs/zh/collection/merge-with.md b/docs/zh/collection/merge-with.md
index c6eb93c..2faf831 100644
--- a/docs/zh/collection/merge-with.md
+++ b/docs/zh/collection/merge-with.md
@@ -2,7 +2,7 @@
 
 递归合并两个对象，可通过回调函数自定义合并逻辑。
 
-### 用法
+### 使用
 
 ```ts
 import { mergeWith } from 'rattail'
diff --git a/docs/zh/collection/merge.md b/docs/zh/collection/merge.md
index 594e925..74ce854 100644
--- a/docs/zh/collection/merge.md
+++ b/docs/zh/collection/merge.md
@@ -2,7 +2,7 @@
 
 递归合并两个对象。
 
-### 用法
+### 使用
 
 ```ts
 import { merge } from 'rattail'
diff --git a/docs/zh/file/to-array-buffer.md b/docs/zh/file/to-array-buffer.md
index ea643b0..aa98208 100644
--- a/docs/zh/file/to-array-buffer.md
+++ b/docs/zh/file/to-array-buffer.md
@@ -2,7 +2,7 @@
 
 将 `File` 对象转换为 `ArrayBuffer`。
 
-### 用法
+### 使用
 
 ```ts
 import { toArrayBuffer } from 'rattail'
diff --git a/docs/zh/file/to-data-url.md b/docs/zh/file/to-data-url.md
index a577061..38e5586 100644
--- a/docs/zh/file/to-data-url.md
+++ b/docs/zh/file/to-data-url.md
@@ -2,7 +2,7 @@
 
 将 `File` 对象转换为 Data URL 字符串。
 
-### 用法
+### 使用
 
 ```ts
 import { toDataURL } from 'rattail'
diff --git a/docs/zh/file/to-text.md b/docs/zh/file/to-text.md
index 3175bee..b8e9361 100644
--- a/docs/zh/file/to-text.md
+++ b/docs/zh/file/to-text.md
@@ -2,7 +2,7 @@
 
 将 `File` 对象转换为文本字符串。
 
-### 用法
+### 使用
 
 ```ts
 import { toText } from 'rattail'
diff --git a/docs/zh/util/cancel-animation-frame.md b/docs/zh/util/cancel-animation-frame.md
index 51c860b..db839d0 100644
--- a/docs/zh/util/cancel-animation-frame.md
+++ b/docs/zh/util/cancel-animation-frame.md
@@ -2,7 +2,7 @@
 
 使用给定的句柄取消 `requestAnimationFrame` 请求，并使用 `clearTimeout` 作为回退选项。
 
-### 用法
+### 使用
 
 ```ts
 import { cancelAnimationFrame } from 'rattail'
diff --git a/docs/zh/util/classes.md b/docs/zh/util/classes.md
index 090dd1f..65df0d6 100644
--- a/docs/zh/util/classes.md
+++ b/docs/zh/util/classes.md
@@ -2,7 +2,7 @@
 
 根据给定条件生成类名列表，或直接返回类名。
 
-### 用法
+### 使用
 
 ```ts
 import { classes } from 'rattail'
diff --git a/docs/zh/util/create-namespace-fn.md b/docs/zh/util/create-namespace-fn.md
index 5750ee0..cf235ef 100644
--- a/docs/zh/util/create-namespace-fn.md
+++ b/docs/zh/util/create-namespace-fn.md
@@ -2,7 +2,7 @@
 
 创建一个命名空间函数，用于生成 BEM 样式的组件和类名。
 
-### 用法
+### 使用
 
 ```ts
 import { createNamespaceFn } from 'rattail'
diff --git a/docs/zh/util/double-raf.md b/docs/zh/util/double-raf.md
index a11a2de..7800bcb 100644
--- a/docs/zh/util/double-raf.md
+++ b/docs/zh/util/double-raf.md
@@ -2,7 +2,7 @@
 
 创建一个基于 `Promise` 的双重 `requestAnimationFrame`，在两帧之后 `resolved`。
 
-### 用法
+### 使用
 
 ```ts
 import { doubleRaf } from 'rattail'
diff --git a/docs/zh/util/get-all-parent-scroller.md b/docs/zh/util/get-all-parent-scroller.md
index 1a4bf7b..8a8dc86 100644
--- a/docs/zh/util/get-all-parent-scroller.md
+++ b/docs/zh/util/get-all-parent-scroller.md
@@ -2,7 +2,7 @@
 
 获取元素的所有可滚动父级元素，包含 `window` 作为最后一项。
 
-### 用法
+### 使用
 
 ```ts
 import { getAllParentScroller } from 'rattail'
diff --git a/docs/zh/util/get-parent-scroller.md b/docs/zh/util/get-parent-scroller.md
index 59d50c3..245d77d 100644
--- a/docs/zh/util/get-parent-scroller.md
+++ b/docs/zh/util/get-parent-scroller.md
@@ -2,7 +2,7 @@
 
 查找元素的最近可滚动父级元素。如果没有找到滚动父级，则返回 `window`。
 
-### 用法
+### 使用
 
 ```ts
 import { getParentScroller } from 'rattail'
diff --git a/docs/zh/util/get-rect.md b/docs/zh/util/get-rect.md
index e2eacdc..5861b81 100644
--- a/docs/zh/util/get-rect.md
+++ b/docs/zh/util/get-rect.md
@@ -2,7 +2,7 @@
 
 获取元素或窗口的尺寸和位置，返回一个 `DOMRect` 对象。
 
-### 用法
+### 使用
 
 ```ts
 import { getRect } from 'rattail'
diff --git a/docs/zh/util/get-scroll-left.md b/docs/zh/util/get-scroll-left.md
index e97a30a..a1ffec2 100644
--- a/docs/zh/util/get-scroll-left.md
+++ b/docs/zh/util/get-scroll-left.md
@@ -2,7 +2,7 @@
 
 获取元素或窗口的水平滚动位置。
 
-### 用法
+### 使用
 
 ```ts
 import { getScrollLeft } from 'rattail'
diff --git a/docs/zh/util/get-scroll-top.md b/docs/zh/util/get-scroll-top.md
index 6ee3e52..11799a2 100644
--- a/docs/zh/util/get-scroll-top.md
+++ b/docs/zh/util/get-scroll-top.md
@@ -2,7 +2,7 @@
 
 获取元素或窗口的垂直滚动位置。
 
-### 用法
+### 使用
 
 ```ts
 import { getScrollTop } from 'rattail'
diff --git a/docs/zh/util/get-style.md b/docs/zh/util/get-style.md
index 3d04f47..8dc2b08 100644
--- a/docs/zh/util/get-style.md
+++ b/docs/zh/util/get-style.md
@@ -2,7 +2,7 @@
 
 获取给定 DOM 元素的计算 CSS 样式。
 
-### 用法
+### 使用
 
 ```ts
 import { getStyle } from 'rattail'
diff --git a/docs/zh/util/in-viewport.md b/docs/zh/util/in-viewport.md
index 75cf5e1..63ed5e6 100644
--- a/docs/zh/util/in-viewport.md
+++ b/docs/zh/util/in-viewport.md
@@ -2,7 +2,7 @@
 
 判断元素是否在视口内可见。
 
-### 用法
+### 使用
 
 ```ts
 import { inViewport } from 'rattail'
diff --git a/docs/zh/util/mitt.md b/docs/zh/util/mitt.md
index d55971d..1b580b8 100644
--- a/docs/zh/util/mitt.md
+++ b/docs/zh/util/mitt.md
@@ -2,7 +2,7 @@
 
 事件调度器，集成了 [mitt](https://github.com/developit/mitt)。
 
-### 用法
+### 使用
 
 ```ts
 import { mitt } from 'rattail'
diff --git a/docs/zh/util/pretty-JSON-object.md b/docs/zh/util/pretty-JSON-object.md
new file mode 100644
index 0000000..716f8e4
--- /dev/null
+++ b/docs/zh/util/pretty-JSON-object.md
@@ -0,0 +1,33 @@
+# prettyJSONObject
+
+格式化 `JSON` 对象，增加缩进以便于阅读。
+
+### 使用
+
+```ts
+import { prettyJSONObject } from 'rattail'
+
+const jsonObject = { key: 'value', nested: { key: 'nestedValue' } }
+const pretty = prettyJSONObject(jsonObject)
+console.log(pretty)
+/*
+{
+  "key": "value",
+  "nested": {
+    "key": "nestedValue"
+  }
+}
+*/
+```
+
+### 参数
+
+| 参数         | 类型     | 默认值 |
+| ------------ | -------- | ------ |
+| `jsonObject` | `object` |        |
+
+### 返回值
+
+| 类型     |
+| -------- |
+| `string` |
diff --git a/docs/zh/util/prevent-default.md b/docs/zh/util/prevent-default.md
index 0541517..3c22465 100644
--- a/docs/zh/util/prevent-default.md
+++ b/docs/zh/util/prevent-default.md
@@ -2,7 +2,7 @@
 
 阻止事件的默认行为（如果该事件可取消）。
 
-### 用法
+### 使用
 
 ```ts
 import { preventDefault } from 'rattail'
diff --git a/docs/zh/util/raf.md b/docs/zh/util/raf.md
index ada6cb5..b92c898 100644
--- a/docs/zh/util/raf.md
+++ b/docs/zh/util/raf.md
@@ -2,7 +2,7 @@
 
 创建一个基于 `Promise` 的 `requestAnimationFrame`，在下一帧时 `resolved`。
 
-### 用法
+### 使用
 
 ```ts
 import { raf } from 'rattail'
diff --git a/docs/zh/util/request-animation-frame.md b/docs/zh/util/request-animation-frame.md
index c551e6f..e8b6fbe 100644
--- a/docs/zh/util/request-animation-frame.md
+++ b/docs/zh/util/request-animation-frame.md
@@ -2,7 +2,7 @@
 
 提供跨浏览器兼容的 `requestAnimationFrame` 函数，并使用 `setTimeout` 作为回退选项。
 
-### 用法
+### 使用
 
 ```ts
 import { requestAnimationFrame } from 'rattail'
diff --git a/docs/zh/util/try-parse-JSON.md b/docs/zh/util/try-parse-JSON.md
new file mode 100644
index 0000000..0302896
--- /dev/null
+++ b/docs/zh/util/try-parse-JSON.md
@@ -0,0 +1,29 @@
+# tryParseJSON
+
+尝试解析 `JSON` 字符串。如果解析失败，返回 `undefined`。
+
+### 使用
+
+```ts
+import { tryParseJSON } from 'rattail'
+
+const jsonString = '{"key": "value"}'
+const parsed = tryParseJSON(jsonString)
+console.log(parsed) // { key: "value" }
+
+const invalidJsonString = '{"key": value}'
+const invalidParsed = tryParseJSON(invalidJsonString)
+console.log(invalidParsed) // undefined
+```
+
+### 参数
+
+| 参数   | 类型     | 默认值 |
+| ------ | -------- | ------ |
+| `json` | `string` |        |
+
+### 返回值
+
+| 类型                  |
+| --------------------- |
+| `object \| undefined` |