From d4bed9a8006c8494e5ccd8386791500d808bf5f4 Mon Sep 17 00:00:00 2001
From: dalaoshu <laipichan@qq.com>
Date: Fri, 27 Sep 2024 14:29:06 +0800
Subject: [PATCH] docs(linter): improve docs for node/security/tree_shaking
 rules (#6097)

Related to #6050

As of this PR, all documents of that contain a few rules have been
corrected.
---
 .../src/rules/node/no_exports_assign.rs           |  1 +
 .../oxc_linter/src/rules/security/api_keys/mod.rs |  1 +
 .../no_side_effects_in_initialization/mod.rs      | 15 +++++++++++++--
 3 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/crates/oxc_linter/src/rules/node/no_exports_assign.rs b/crates/oxc_linter/src/rules/node/no_exports_assign.rs
index af3cd8b7d..caa8f3c3b 100644
--- a/crates/oxc_linter/src/rules/node/no_exports_assign.rs
+++ b/crates/oxc_linter/src/rules/node/no_exports_assign.rs
@@ -40,6 +40,7 @@ pub struct NoExportsAssign;
 
 declare_oxc_lint!(
     /// ### What it does
+    ///
     /// Disallows assignment to `exports`.
     ///
     /// ### Why is this bad?
diff --git a/crates/oxc_linter/src/rules/security/api_keys/mod.rs b/crates/oxc_linter/src/rules/security/api_keys/mod.rs
index e4f1501cc..dd35e7ae6 100644
--- a/crates/oxc_linter/src/rules/security/api_keys/mod.rs
+++ b/crates/oxc_linter/src/rules/security/api_keys/mod.rs
@@ -57,6 +57,7 @@ declare_oxc_lint!(
     /// ```
     ///
     /// ### What To Do Instead
+    ///
     /// :::warning
     /// The Oxc team are not security experts. We do not endorse any particular
     /// key management service or strategy. Do your research and choose the best
diff --git a/crates/oxc_linter/src/rules/tree_shaking/no_side_effects_in_initialization/mod.rs b/crates/oxc_linter/src/rules/tree_shaking/no_side_effects_in_initialization/mod.rs
index f9a494ef3..9d82923d2 100644
--- a/crates/oxc_linter/src/rules/tree_shaking/no_side_effects_in_initialization/mod.rs
+++ b/crates/oxc_linter/src/rules/tree_shaking/no_side_effects_in_initialization/mod.rs
@@ -116,12 +116,23 @@ declare_oxc_lint!(
     ///
     /// ### Why is this bad?
     ///
-    /// ### Example
+    /// Side-effects in module initialization can hinder tree-shaking, which aims to remove
+    /// unused code. If side-effects exist, it's harder for the bundler to safely eliminate
+    /// code, leading to larger bundles and potentially unexpected behavior. Ensuring minimal
+    /// side-effects allows bundlers to optimize code effectively.
     ///
+    /// ### Examples
+    ///
+    /// Examples of **incorrect** code for this rule:
     /// ```javascript
     /// myGlobal = 17; // Cannot determine side-effects of assignment to global variable
     /// const x = { [globalFunction()]: "myString" }; // Cannot determine side-effects of calling global function
-    /// export default 42;
+    /// ```
+    ///
+    /// Examples of **correct** code for this rule:
+    /// ```javascript
+    /// const localVar = 17; // Local variable assignment, no global side-effects
+    /// export default 42; // Pure export with no side-effects
     /// ```
     ///
     /// ### Options