Add brief documentation

mbrandau · Oct 9, 2018 · d47f576 · d47f576
1 parent 0e62e55
commit d47f576
Show file tree

Hide file tree

Showing 2 changed files with 84 additions and 0 deletions.
diff --git a/lib/index.js b/lib/index.js
@@ -7,6 +7,10 @@ var IdGenerator = require('./idGenerator');
 var CLASS_NAME_REGEX = /\/\*[\s\S]*?\*\/|(\.[a-z_-][\w-]*)(?=[^{}]*{)/g; // https://stackoverflow.com/a/48962872/5133130
 
 var HTML_CLASS_REGEX = /class="([\w-\s]*)"/g;
+/**
+ * Provides methods to replaces CSS class names
+ * @constructor
+ */
 
 var CssShortener = function CssShortener(options) {
   if (!options) options = {};
@@ -38,10 +42,21 @@ var CssShortener = function CssShortener(options) {
 
     return "class=\"".concat(result, "\"");
   };
+  /**
+   * Returns all mapped CSS class names
+   * @returns {object}
+   */
+
 
   this.getMap = function () {
     return this._classNameMap;
   };
+  /**
+   * Imports mapped CSS class names
+   * @param {object} map Map that should be imported
+   * @param {boolean} override If true, existing mappings will be overridden
+   */
+
 
   this.importMap = function (map, override) {
     for (var classNameToImport in map) {
@@ -52,6 +67,12 @@ var CssShortener = function CssShortener(options) {
 
     }
   };
+  /**
+   * Generates and maps a new class name
+   * @param className The existing class name that should be replaced
+   * @returns {string} The new generated and mapped class name
+   */
+
 
   this.getNewClassName = function (className) {
     // If the ignorePrefix option is set and the current class starts with the prefix, trim the prefix off and ignore the class.
@@ -60,18 +81,40 @@ var CssShortener = function CssShortener(options) {
     if (t._classNameMap[className] != null) return t._classNameMap[className]; // Generate, map and return the new class name
     else return t._classNameMap[className] = t._idGenerator();
   };
+  /**
+   * @returns {Transform} A transform stream that replaces class names in the CSS code
+   */
+
 
   this.cssStream = function () {
     return replaceStream(CLASS_NAME_REGEX, replaceCss);
   };
+  /**
+   * Replaces class names in the given CSS code.
+   * @param css The CSS code in which class names will be replaced
+   * @returns {string}
+   */
+
 
   this.replaceCss = function (css) {
     return css.replace(CLASS_NAME_REGEX, replaceCss);
   };
+  /**
+   * Class names will only be replaced with the existing mappings. No mappings will be generated.
+   * @returns {Transform} A transform stream that replaces class names in the HTML code
+   */
+
 
   this.htmlStream = function () {
     return replaceStream(HTML_CLASS_REGEX, replaceHtml);
   };
+  /**
+   * Replaces class names in the given HTML code.
+   * Class names will only be replaced with the existing mappings. No mappings will be generated.
+   * @param html The HTML code in which class names will be replaced
+   * @returns {string}
+   */
+
 
   this.replaceHtml = function (html) {
     return html.replace(HTML_CLASS_REGEX, replaceHtml);

diff --git a/src/index.js b/src/index.js
@@ -4,6 +4,10 @@ const IdGenerator = require('./idGenerator');
 const CLASS_NAME_REGEX = /\/\*[\s\S]*?\*\/|(\.[a-z_-][\w-]*)(?=[^{}]*{)/g; // https://stackoverflow.com/a/48962872/5133130
 const HTML_CLASS_REGEX = /class="([\w-\s]*)"/g;
 
+/**
+ * Provides methods to replaces CSS class names
+ * @constructor
+ */
 const CssShortener = function(options) {
   if (!options) options = {};
   this._options = options;
@@ -37,9 +41,19 @@ const CssShortener = function(options) {
     return `class="${result}"`;
   };
 
+  /**
+   * Returns all mapped CSS class names
+   * @returns {object}
+   */
   this.getMap = function() {
     return this._classNameMap;
   };
+
+  /**
+   * Imports mapped CSS class names
+   * @param {object} map Map that should be imported
+   * @param {boolean} override If true, existing mappings will be overridden
+   */
   this.importMap = function(map, override) {
     for (let classNameToImport in map) {
       if (this._classNameMap[classNameToImport] != null) {
@@ -50,6 +64,11 @@ const CssShortener = function(options) {
     }
   };
 
+  /**
+   * Generates and maps a new class name
+   * @param className The existing class name that should be replaced
+   * @returns {string} The new generated and mapped class name
+   */
   this.getNewClassName = function(className) {
     // If the ignorePrefix option is set and the current class starts with the prefix, trim the prefix off and ignore the class.
     if (
@@ -65,15 +84,37 @@ const CssShortener = function(options) {
     // Generate, map and return the new class name
     else return (t._classNameMap[className] = t._idGenerator());
   };
+
+  /**
+   * @returns {Transform} A transform stream that replaces class names in the CSS code
+   */
   this.cssStream = function() {
     return replaceStream(CLASS_NAME_REGEX, replaceCss);
   };
+
+  /**
+   * Replaces class names in the given CSS code.
+   * @param css The CSS code in which class names will be replaced
+   * @returns {string}
+   */
   this.replaceCss = function(css) {
     return css.replace(CLASS_NAME_REGEX, replaceCss);
   };
+
+  /**
+   * Class names will only be replaced with the existing mappings. No mappings will be generated.
+   * @returns {Transform} A transform stream that replaces class names in the HTML code
+   */
   this.htmlStream = function() {
     return replaceStream(HTML_CLASS_REGEX, replaceHtml);
   };
+
+  /**
+   * Replaces class names in the given HTML code.
+   * Class names will only be replaced with the existing mappings. No mappings will be generated.
+   * @param html The HTML code in which class names will be replaced
+   * @returns {string}
+   */
   this.replaceHtml = function(html) {
     return html.replace(HTML_CLASS_REGEX, replaceHtml);
   };