From 2e8df8ae1442d488b5223bf85632ad84a27c9994 Mon Sep 17 00:00:00 2001
From: Marcos Caceres <marcos@marcosc.com>
Date: Thu, 28 Dec 2023 18:09:55 +1100
Subject: [PATCH] refactor(core/style): improve code comments a bit more

---
 src/core/style.js | 32 ++++++++++++++++++++------------
 1 file changed, 20 insertions(+), 12 deletions(-)

diff --git a/src/core/style.js b/src/core/style.js
index c993b92185..88d8ad53a5 100644
--- a/src/core/style.js
+++ b/src/core/style.js
@@ -1,21 +1,25 @@
-// @ts-check
 // Module core/style
-// Inserts the CSS that ReSpec uses into the document.
-//
-// IMPORTANT NOTE
-//  To add you own styles, create a plugin that declares the css as a dependency
-//  and create a build of your new ReSpec profile.
-//
-// CONFIGURATION
-//  - noReSpecCSS: if you're using a profile that loads this module but you don't want
-//    the style, set this to true
-import css from "../styles/respec.css.js";
+// The purpose of this module is to insert the default ReSpec CSS into the document.
+// If you don't want to use the default ReSpec CSS, set the `noReSpecCSS` configuration
+// option to `true`. If you want to use your own styles, create a ReSpec profile that
+// includes your own styles and sets the `noReSpecCSS` configuration option to `true`.
 
+/**
+ * Module Name.
+ * @type {string}
+ */
 export const name = "core/style";
 
-// Opportunistically inserts the style, with the chance to reduce some FOUC
+import css from "../styles/respec.css.js";
+
+// Opportunistically inserts the style to reduce some FOUC.
+/** @type {HTMLStyleElement} */
 const styleElement = insertStyle();
 
+/**
+ * Inserts the ReSpec CSS as a `style` element into the document's `head`.
+ * @return {HTMLStyleElement} The `style` element that was inserted.
+ */
 function insertStyle() {
   const styleElement = document.createElement("style");
   styleElement.id = "respec-mainstyle";
@@ -24,6 +28,10 @@ function insertStyle() {
   return styleElement;
 }
 
+/**
+ * Removes the ReSpec CSS if the `noReSpecCSS` configuration option is `true`.
+ * @param {object} conf The document configuration object.
+ */
 export function run(conf) {
   if (conf.noReSpecCSS) {
     styleElement.remove();