Initial jsdoc implementation. yarn gendocs

.gitignore

@@ -1,6 +1,7 @@
 .DS_Store
 node_modules/
 dist/
+srcdocs/
 npm-debug.log
 test/unit/coverage
 src/res/locales/available.json

jsdoc.json

@@ -0,0 +1,22 @@
+{
+    "plugins": ["plugins/markdown"],
+    "recurseDepth": 10,
+    "source": {
+        "include": "src/",
+        "includePattern": ".+\\.js(doc|x)?$",
+        "excludePattern": "(^|\\/|\\\\)_"
+    },
+    "sourceType": "module",
+    "tags": {
+        "allowUnknownTags": true,
+        "dictionaries": ["jsdoc","closure"]
+    },
+    "templates": {
+        "cleverLinks": false,
+        "monospaceLinks": false
+    },
+    "opts": {
+        "destination": "./srcdocs/",
+        "recurse": true
+    }
+}

package.json

@@ -13,7 +13,8 @@
     "lint:eslint": "eslint --ext .js,.vue src test/unit/specs",
     "lint:stylelint": "stylelint \"src/**/*.{vue,htm,html,css,sss,less,scss}\"",
     "lint": "npm run lint:eslint && npm run lint:stylelint",
-    "lint:fix": "npm run lint:eslint -- --fix && npm run lint:stylelint -- --fix"
+    "lint:fix": "npm run lint:eslint -- --fix && npm run lint:stylelint -- --fix",
+    "gendocs": "rm -rf srcdocs/ && jsdoc -c jsdoc.json"
   },
   "engines": {
     "node": ">=6",
@@ -92,6 +93,7 @@
     "express": "^4.13.3",
     "http-proxy-middleware": "^0.17.2",
     "inject-loader": "^2.0.1",
+    "jsdoc": "^3.5.5",
     "karma": "^1.3.0",
     "karma-coverage": "^1.1.1",
     "karma-mocha": "^1.2.0",

src/helpers/Colours.js

@@ -1,11 +1,13 @@
 'kiwi public';
 
+/** @module */
+
 /**
  * Converts a hex CSS color value to RGB.
  * Adapted from http://stackoverflow.com/a/5624139.
  *
- * @param   String  hex     The hexadecimal color value
- * @return  Object          The RGB representation
+ * @param   {String}  _hex     The hexadecimal color value
+ * @return  {Object}          The RGB representation
  */
 export function hex2rgb(_hex) {
     // Expand shorthand form (e.g. "03F") to full form (e.g. "0033FF")
@@ -22,8 +24,8 @@ export function hex2rgb(_hex) {
 
 /**
  * Converts an RGB color value to a hex string.
- * @param  Object rgb RGB as r, g, and b keys
- * @return String     Hex color string
+ * @param  {Object} rgb RGB as r, g, and b keys
+ * @return {String}     Hex color string
  */
 export function rgb2hex(rgb) {
     return '#' + ['r', 'g', 'b']

src/helpers/Md5.js

@@ -1,5 +1,7 @@
 'kiwi public';
 
+/** @module */
+
 /* eslint-disable */
 // http://www.myersdaily.org/joseph/javascript/md5-text.html
 

src/helpers/Misc.js

@@ -1,11 +1,17 @@
 'kiwi public';
 
+/** @module */
+
 import _ from 'lodash';
 
-// "#chan,#chan2" => 2 channels without a key
-// "#chan,#chan2 key" => 2 channels, the first having a key
-// "#chan,#chan2 key1,key2" => 2 channels, both having a key
-// "#chan,#chan2 ,key2" => 2 channels, the second having a key
+/**
+ * Extract an array of buffers from a string, parsing multiple buffer names and channel keys
+ * "#chan,#chan2" => 2 channels without a key
+ * "#chan,#chan2 key" => 2 channels, the first having a key
+ * "#chan,#chan2 key1,key2" => 2 channels, both having a key
+ * "#chan,#chan2 ,key2" => 2 channels, the second having a key
+ * @param {string} str List of buffer names and channel keys
+ */
 export function extractBuffers(str) {
     let spaceIdx = str.indexOf(' ');
     if (spaceIdx === -1) spaceIdx = str.length;
@@ -28,7 +34,11 @@ export function splitHost(uri) {
 
 }
 
-// Does a string mention a nickname
+/**
+ * Does a string mention a nickname?
+ * @param {string} input The string to search within
+ * @param {string} nick The nick to search for
+ */
 export function mentionsNick(input, nick) {
     let punc = ',.!:;-+)]?¿\\/<>@';
 
@@ -55,7 +65,11 @@ export function mentionsNick(input, nick) {
     return potentialNick.toLowerCase() === nick.toLowerCase();
 }
 
-// Get a users prefix symbol on a buffer from its modes
+/**
+ * Get a users prefix symbol on a buffer from its modes
+ * @param {Object} user The user object
+ * @param {Object} buffer The buffer object
+ */
 export function userModePrefix(user, buffer) {
     // The user may not be on the buffer
     if (!user.buffers[buffer.id]) {
@@ -77,7 +91,11 @@ export function userModePrefix(user, buffer) {
         '';
 }
 
-// Get a users mode on a buffer
+/**
+ * Get a users mode on a buffer
+ * @param user {Object} The user object
+ * @param buffer {Object} The buffer object
+ */
 export function userMode(user, buffer) {
     // The user may not be on the buffer
     if (!user.buffers[buffer.id]) {
@@ -99,7 +117,11 @@ export function userMode(user, buffer) {
         '';
 }
 
-// Get a query string value from the current URL
+/**
+ * Get a query string value from the current URL
+ * @param {string} _name The query string variable name
+ * @param {string} _url The full URL to extract the variable from
+ */
 export function queryStringVal(_name, _url) {
     let url = _url || window.location.href;
     let name = _.escapeRegExp(_name);
@@ -116,7 +138,10 @@ export function queryStringVal(_name, _url) {
     return decodeURIComponent(results[2].replace(/\+/g, ' '));
 }
 
-// Convert a known error code to a human readable message
+/**
+ * Convert a known error code to a human readable message
+ * @param {string} err The error message from the network connection
+ */
 export function networkErrorMessage(err) {
     let errs = {
         err_unknown_host: 'Unknown domain name or host',
@@ -130,10 +155,13 @@ export function networkErrorMessage(err) {
     return errs[err] || 'Unknown error';
 }
 
+/**
+ * Parse a connection string into an object
+ * E.g. [ircs?://]irc.network.net:[+]6667/channel?nick=mynick;
+ * Multiple connections may be given, separated by ;
+ * @param {string} str The connection string URI
+ */
 export function parseIrcUri(str) {
-    // [ircs?://]irc.network.net:[+]6667/channel?nick=mynick;
-    // Parse connection string such as this ^ into an object. Multiple connections
-    // may be given, separated by ;
     let reg = /(?:(ircs?):\/\/)?([a-z.0-9]+)(?::(?:(\+)?([0-9]+)))?(?:\/([^?]*))?(?:\?(.*))?/;
     let connections = [];
     str.split(';').forEach((connectionString) => {
@@ -184,7 +212,10 @@ export function parseIrcUri(str) {
     return connections;
 }
 
-// Scan though an object and extend any dot notated keys
+/**
+ * Scan though an object and extend any dot notated keys
+ * @param {Object} confObj Source object to traverse
+ */
 export function dedotObject(confObj, _place) {
     let place = _place || [];
     let regex = /\w\.\w/;
@@ -202,14 +233,18 @@ export function dedotObject(confObj, _place) {
     });
 }
 
-// Replace the target object with source, while keeping the target object reference intact.
-// Delete all the properties from the target object and copy the properties from source
-// over to the target.
-// a = {one: 1, two: 2, three: 3}
-// b = {four: 4, five: 5, six: 6}
-// replaceObjectProps(a, b)
-// a.one === undefined;
-// a.six === 6;
+/**
+ * Replace the target object with source, while keeping the target object reference intact.
+ * Delete all the properties from the target object and copy the properties from source
+ * over to the target.
+ * a = {one: 1, two: 2, three: 3}
+ * b = {four: 4, five: 5, six: 6}
+ * replaceObjectProps(a, b)
+ * a.one === undefined;
+ * a.six === 6;
+ * @param {Object} target The target object that will be replaced
+ * @param {Object} source The source object from which all properties will be copied from
+ */
 export function replaceObjectProps(target, source) {
     Object.keys(target).forEach(prop => delete target[prop]);
     Object.keys(source).forEach((prop) => { target[prop] = source[prop]; });

src/helpers/TextFormatting.js

@@ -1,5 +1,7 @@
 'kiwi public';
 
+/** @module */
+
 import state from '@/libs/state';
 import ThemeManager from '@/libs/ThemeManager';
 import _ from 'lodash';

src/libs/AliasRewriter.js

@@ -1,18 +1,19 @@
 'kiwi public';
 
+/** @module */
+
 /**
  * Command input Alias + re-writing
  *
  * Variables used in aliases:
- *     $0 = the command being run
- *     $1 = first param of input
- *     $N = Nth param of input
- *     $1+2 = first param of input and the next 2 words
- *     $2+4 = second param of input and the next 4 words
- *     $2+ = second param of input and all words after
- *     $variable = variable as set in the vars object
+ * - $0 = the command being run
+ * - $1 = first param of input
+ * - $N = Nth param of input
+ * - $1+2 = first param of input and the next 2 words
+ * - $2+4 = second param of input and the next 4 words
+ * - $2+ = second param of input and all words after
+ * - $variable = variable as set in the vars object
  */
-
 export default class AliasRewriter {
     constructor() {
         // Max alias recursion depth
@@ -23,6 +24,7 @@ export default class AliasRewriter {
         this.aliases = {};
     }
 
+    /** Reset the current aliases object from a newline delimited string of aliases */
     importFromString(str) {
         // Clear out the current aliases before adding new ones in
         this.aliases = {};
@@ -128,6 +130,7 @@ export default class AliasRewriter {
         return compiled;
     }
 
+    /** Take a string input, process any aliases and output the finalised string */
     process(input, vars) {
         let line = input || '';
         let words = line.split(' ');

src/libs/AudioBleep.js

@@ -1,5 +1,10 @@
 'kiwi public';
 
+/** @module */
+
+/**
+ * Plays alert sounds
+ */
 export class AudioBleep {
     constructor() {
         this.lastPlayed = 0;
@@ -18,6 +23,7 @@ export class AudioBleep {
         this.audio.appendChild(source);
     }
 
+    /** Play the alert sound */
     play() {
         // Only play the bleep once every 2 seconds
         if (!this.lastPlayed || Date.now() - this.lastPlayed > 2000) {
@@ -27,6 +33,7 @@ export class AudioBleep {
     }
 }
 
+/** Watch the Kiwi state for any message highlights and play an alert */
 export function listenForHighlights(state) {
     let bleep = new AudioBleep();
 

src/libs/BouncerMiddleware.js

@@ -1,7 +1,12 @@
 'kiwi public';
 
+/** @module */
+
 import strftime from 'strftime';
 
+/**
+ * Adds the BOUNCER IRCv3 spec to irc-framework
+ */
 export default function bouncerMiddleware() {
     let networks = [];
     let buffers = {};