From 1a4d147b8687e930a76eda95bc89b29244ac1f6a Mon Sep 17 00:00:00 2001
From: Okinea Dev <okineadev@users.noreply.github.com>
Date: Wed, 30 Oct 2024 08:51:37 +0000
Subject: [PATCH] chore(docs): add useful comments and update issue templates

---
 .gitattributes                            |  2 ++
 .github/ISSUE_TEMPLATE/1-icon-request.yml |  4 +++-
 .github/ISSUE_TEMPLATE/2-bug-report.yml   |  8 ++++----
 .gitignore                                | 19 +++++++++++++++++++
 .vscodeignore                             |  5 +++++
 material-colors.yml                       | 10 ++++++++--
 svgo.config.js                            |  8 +++++++-
 7 files changed, 48 insertions(+), 8 deletions(-)

diff --git a/.gitattributes b/.gitattributes
index 59f21f97f7..a5ae34efe3 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -1,3 +1,5 @@
+# See https://git-scm.com/docs/gitattributes#_pattern_format for more about `.gitattributes`.
+
 # Normalize EOL for all files that Git considers text files
 * text=auto eol=lf
 
diff --git a/.github/ISSUE_TEMPLATE/1-icon-request.yml b/.github/ISSUE_TEMPLATE/1-icon-request.yml
index c30032e865..e337335c62 100644
--- a/.github/ISSUE_TEMPLATE/1-icon-request.yml
+++ b/.github/ISSUE_TEMPLATE/1-icon-request.yml
@@ -37,7 +37,9 @@ body:
     id: graphic-ideas
     attributes:
       label: Graphic ideas
-      description: A clear description of the icon you would like. If the icons are separate for folder and files, please create separate issues.
+      description: |
+        A clear description of the icon you would like.
+        If the icons are separate for folder and files, please create separate issues.
       placeholder: Include a link to sample icons if possible
 
   - type: textarea
diff --git a/.github/ISSUE_TEMPLATE/2-bug-report.yml b/.github/ISSUE_TEMPLATE/2-bug-report.yml
index 43e43e3b17..01a0f7fd43 100644
--- a/.github/ISSUE_TEMPLATE/2-bug-report.yml
+++ b/.github/ISSUE_TEMPLATE/2-bug-report.yml
@@ -13,7 +13,7 @@ body:
     id: description
     attributes:
       label: Describe the bug
-      description: Describe the bug clearly
+      description: Provide a detailed description of the bug
     validations:
       required: true
 
@@ -34,7 +34,7 @@ body:
     id: expected
     attributes:
       label: Expected behavior
-      description: A clear and concise description of what you expected to happen
+      description: What you expected to happen
     validations:
       required: true
 
@@ -42,7 +42,7 @@ body:
     id: screenshots
     attributes:
       label: Screenshots
-      description: If applicable, add screenshots to help explain your problem
+      description: Add screenshots if applicable
     validations:
       required: false
 
@@ -64,7 +64,7 @@ body:
     id: additional-context
     attributes:
       label: Additional context
-      description: Add any other context about the problem here.
+      description: Additional context about the problem.
     validations:
       required: false
 
diff --git a/.gitignore b/.gitignore
index 1a47c83859..b9d46366d5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,11 +1,17 @@
+# See https://git-scm.com/docs/gitignore#_pattern_format for more about ignoring files.
+
+# Ignore build output directories
 out
 dist
 
+# Ignore node_modules directory
 node_modules
 
+# Ignore VS Code test files
 .vscode-test/**
 *.vsix
 
+# Ignore specific icon files and directories
 icons/file.svg
 icons/folder.svg
 icons/folder-open.svg
@@ -14,5 +20,18 @@ icons/folder-root-open.svg
 icons/*.clone.svg
 icons/clones
 
+# Ignore specific HTML files in scripts directories
 src/scripts/preview/*.html
 src/scripts/contributors/*.html
+
+# Ignore cache directory
+.cache
+
+# Ignore log files
+*.log
+
+# Ignore optional eslint cache
+.eslintcache
+
+*.tgz
+*.tgz
diff --git a/.vscodeignore b/.vscodeignore
index e27de6399c..d5b382cb70 100644
--- a/.vscodeignore
+++ b/.vscodeignore
@@ -1,18 +1,23 @@
 # Files to include in the extension package
 # Documentation for this format:
 # https://code.visualstudio.com/api/working-with-extensions/publishing-extension#using-.vscodeignore
+
+# Files for vscode extension
 !CHANGELOG.md
 !LICENSE.md
 !README.md
 !logo.png
 
+# Translation files
 !package.json
 !package.nls.json
 !package.nls.*.json
 
+# Extension code
 !dist/extension
 !dist/material-icons.json
 
+# Icons
 !icons
 
 # Exclude everything else
diff --git a/material-colors.yml b/material-colors.yml
index ecc7bb3569..4ac97870af 100644
--- a/material-colors.yml
+++ b/material-colors.yml
@@ -1,3 +1,9 @@
+# This YAML file contains a list of color codes used in the VSCode Material Icon Theme.
+# Each color is represented by its hexadecimal code and is categorized by its color name and shade.
+
+# Note:
+# - Black (`#000000`) and White (`#FFFFFF`) cannot not be used.
+
 colors:
   - '#FFEBEE' # red 50
   - '#FFCDD2' # red 100
@@ -253,5 +259,5 @@ colors:
   - '#455A64' # blue gray 700
   - '#37474F' # blue gray 800
   - '#263238' # blue gray 900
-  # - '#000000' # black must not be used
-  # - '#FFFFFF' # white must not be used
+# - '#000000' # black must not be used
+# - '#FFFFFF' # white must not be used
diff --git a/svgo.config.js b/svgo.config.js
index 78c46f2994..7af1314ff4 100644
--- a/svgo.config.js
+++ b/svgo.config.js
@@ -1,6 +1,12 @@
-module.exports = {
+/**
+ * @typedef {import('svgo').Config} SVGOConfig
+ * @typedef {import('svgo').PluginConfig} PluginConfig
+ */
+
+module.exports = /** @type {SVGOConfig} */ {
   multipass: true,
   precision: 2,
+  /** @type {PluginConfig[]} */
   plugins: [
     {
       name: 'preset-default',