Modify JSDoc comments. (eslint does not complain now)

.eslintrc.js

@@ -24,17 +24,18 @@ module.exports = {
             "always"
         ],
         "no-unused-vars": "off",
-        "jsdoc/check-param-names": 1,
-        "jsdoc/check-tag-names": 1,
-        "jsdoc/check-types": 1,
-        "jsdoc/newline-after-description": 1,
+        "jsdoc/check-param-names": 2,
+        "jsdoc/check-tag-names": 2,
+        "jsdoc/check-types": 2,
+        "jsdoc/newline-after-description": 2,
+        "jsdoc/require-description-complete-sentence": 2,
+        "jsdoc/require-hyphen-before-param-description": 2,
+        "jsdoc/require-param": 2,
+        "jsdoc/require-param-description": 2,
+        "jsdoc/require-param-type": 2,
+        "jsdoc/require-returns-description": 2,
+        "jsdoc/require-returns-type": 2,
         "jsdoc/require-description-complete-sentence": 1,
-        "jsdoc/require-hyphen-before-param-description": 1,
-        "jsdoc/require-param": 1,
-        "jsdoc/require-param-description": 1,
-        "jsdoc/require-param-type": 1,
-        "jsdoc/require-returns-description": 1,
-        "jsdoc/require-returns-type": 1,
         "requirejs/no-invalid-define": 2,
         "requirejs/no-multiple-define": 2,
         "requirejs/no-named-define": 2,

sacredboard/static/scripts/enquotedStringOrNumberValidator.js

@@ -5,9 +5,10 @@ define(["knockout"], function (ko) {
      *
      * Allows only enquoted "string" or 123.4 number to be inputted and
      * prevents the "regex" operator from being used with numbers.
-     * @param target - The target observable (value holder).
+     *
+     * @param {ko.observable} target - The target observable (value holder).
      * @param {QueryFilter} queryFilter - The QueryFilter to be checked.
-     * @returns {*} target
+     * @returns {*} Target.
      */
     ko.extenders.validateJSONValue = function (target, queryFilter) {
 

sacredboard/static/scripts/escapeHtml.js

@@ -20,7 +20,7 @@ define([], function () {
      */
     function replace(string) {
         return String(string).replace(/[&<>"'`=\/]/g, function (s) {
-            return entityMap[s]
+            return entityMap[s];
         });
     }
     return replace;

sacredboard/static/scripts/runs/detailView.js

@@ -3,8 +3,8 @@ define(["escapeHtml", "runs/dictionaryBrowser/component", "jquery", "knockout"],
     /**
      * Generate detail view for an experiment run.
      *
-     * @param run {Run} - Run returned via the web service
-     * @returns {string} - HTML representation of the detail
+     * @param {Run} run - Run returned via the web service (/api/run/<id>).
+     * @returns {string} - HTML representation of the detail.
      */
     function generateDetailView(run) {
         // `run` is the original data object for the row

sacredboard/static/scripts/runs/dictionaryBrowser/DictEntry.js

@@ -8,8 +8,8 @@ define(["knockout"], function (ko) {
      * dictionary or array. Its display value is calculated based on the
      * actual value type (array, object, native type).
      *
-     * @param {string} name - The display name of this entry
-     * @param {*} value - The value of the entry (object, array, String, Number, Date, null)
+     * @param {string} name - The display name of this entry.
+     * @param {*} value - The value of the entry (object, array, String, Number, Date, null).
      * @class
      */
     function DictEntry(name, value) {
@@ -28,6 +28,7 @@ define(["knockout"], function (ko) {
     };
     /**
      * Check whether the value of the DictEntry is a complex type.
+     *
      * @returns {boolean} True for objects and arrays, false otherwise.
      */
     DictEntry.prototype.hasChildren = function () {
@@ -36,16 +37,19 @@ define(["knockout"], function (ko) {
     /**
      * Generate an array of DictEntries of nested objects.
      *
-     * Examples:
-     *
-     * DictEntry("me", ["hello", "world"]).getChildren() returns
+     * @example <caption>Array.</caption>
+     * DictEntry("me", ["hello", "world"]).getChildren()
+     * // returns
      * [DictEntry("0", "hello"), DictEntry("1", "world")]
      *
-     * DictEntry("me", {"key1": "value1", "key2": ["hello", "world"]}).getChildren() returns
+     * @example <caption>Object.</caption>
+     * DictEntry("me", {"key1": "value1", "key2": ["hello", "world"]}).getChildren()
+     * // returns
      * [DictEntry("key1", "value1"), DictEntry("key2", ["hello", "world"])]
      *
-     * DictEntry("me", "string").getChildren() returns
-     * []
+     * @example <caption>Native type.</caption>.
+     * DictEntry("me", "string").getChildren()
+     * // returns []
      *
      *
      * @returns {DictEntry[]} Array of DictEntries or an empty array for native value types sorted by their keys.
@@ -86,7 +90,8 @@ define(["knockout"], function (ko) {
 
     /**
      * Get the display name of the DictEntry.
-     * @returns {string} Display name
+     *
+     * @returns {string} Display name.
      */
     DictEntry.prototype.getDisplayName = function () {
         return this.name;
@@ -95,10 +100,17 @@ define(["knockout"], function (ko) {
     /**
      * Return the display value for in-line view.
      *
-     * Example:
-     * for DictEntry("hello", "world") returns "world"
-     * for DictEntry("hello", {"key": "value"}) returns "{...}"
-     * for DictEntry("hello", [1,2,3]) returns "[1, 2, 3]"
+     * @example <caption>Native value.</caption>
+     * DictEntry("hello", "world").getDisplayValue()
+     * // returns "world"
+     *
+     * @example <caption>Object.</caption>
+     * DictEntry("hello", {"key": "value"}).getDisplayValue()
+     * // returns "{...}"
+     *
+     * @example <caption>Array.</caption>
+     * DictEntry("hello", [1,2,3]).getDisplayValue()
+     * // returns "[1, 2, 3]"
      *
      * @returns {string} String representation of the value.
      */

sacredboard/static/scripts/runs/filters/queryFilter.js

@@ -10,12 +10,13 @@ define(["knockout", "enquotedStringOrNumberValidator"],
          * A terminal clause is a terminal part of the whole query.
          * It means that it cannot contain subclauses.
          *
-         * Example: QueryFilter("host.hostname", "!=", "node1")
+         * @example
+         * QueryFilter("host.hostname", "!=", "node1")
          *
          * @param {string} field - The database field to be filtered by.
-         * @param {string} operator - The operator to be used. {@link QueryFilters.operators)
+         * @param {string} operator - The operator to be used. {@link QueryFilters.operators).
          * @param {string|Number} value - The value to be applied in the filter (a primitive type).
-         * @constructor
+         * @class
          * @alias module:runs/filter/queryFilter
          */
         function QueryFilter(field, operator, value) {
@@ -103,20 +104,23 @@ define(["knockout", "enquotedStringOrNumberValidator"],
 
             /**
              * Return a copy of the object.
-             * @returns {QueryFilter}
+             *
+             * @returns {QueryFilter} A copy of the current object.
              */
             this.clone = function () {
                 return new QueryFilter(this.field(), this.operator(), this.value());
             };
 
             /**
              * A serialiable Data Transfer Object of a QueryFilter.
+             *
              * @typedef {{field: String, operator: String, value: primitive}} QueryFilterDto
              */
             /**
              * Convert QueryFilter to its Data Transfer Object.
              *
-             * @returns QueryFilterDto
+             * @returns {QueryFilterDto} A simple object representing
+             * the filter for serialisation as requested by the Sacredboard API.
              */
             this.toDto = function () {
                 return {

sacredboard/static/scripts/runs/filters/queryFilters.js

@@ -5,24 +5,29 @@ define(["knockout", "jquery"],
          * The QueryFilters object is a set of filters to be applied together.
          *
          * A query like "(A == 1 AND B < 10) OR (X == 'hello')"
-         * can be constructed in the following way:
+         * can be constructed using the following example.
          * <pre><code>
          * new QueryFilters("or", [ new QueryFilter('X', '==', 'hello'),
          *                          new QueryFilters('and', [
          *                              new QueryFilter('A', '==', 1),
          *                              new QueryFilter('B', '<', 10)
          *                                          ])
          *                 ]);
-         * </code></pre>
-         * @param {String} type - either 'and' or 'or'. Default: 'and'
-         * @param {QueryFilter[]|QueryFilters[]} filters
+         * </code></pre>.
+         *
+         * @param {string} type - Either 'and' or 'or'. Default: 'and'.
+         * @param {QueryFilter[]|QueryFilters[]} filters - An array of clauses to be joined using the "type" operator.
          * @exports QueryFilters
-         * @constructor
+         * @class
          */
         function QueryFilters(type, filters) {
             var self = this;
             this.filters = ko.observableArray(filters == undefined ? [] : filters);
             this.filters.extend({notify: "always"});
+            // Expected operator types:
+            /* TODO: Better to move it to the view or to QueryFilter as it has nothing much to do with QueryFilters
+            Furthermore, it might be necessary to adjust the view so that it does not search for the operator list here.
+             */
             this.operators = ["==", "!=", "<", "<=", ">", ">=", "regex"];
             this.type = ko.observable(type == undefined ? "and" : type);
             self.addFilter = function (filter) {
@@ -39,8 +44,9 @@ define(["knockout", "jquery"],
              */
             /**
              * Transform QueryFilters to its Data Transfer Object that can be
-             * serialized and sent to backend.
-             * @return QueryFiltersDto
+             * serialized and sent to the backend.
+             *
+             * @returns {QueryFiltersDto} A QueryFilter object accepted by the Sacredboard backend API.
              */
             self.toDto = function () {
                 return {

sacredboard/static/scripts/runs/runTable.js

@@ -7,8 +7,9 @@
 define(["bootstrap", "datatable", "datatables-bootstrap", "runs/detailView", "jquery"],
     function (bootstrap, datatables, dtboostrap, generateDetailView, $) {
         /**
-         * Scrolls down in the element
-         * @param obj
+         * Scroll down in the element.
+         *
+         * @param {DOMNode} obj - The element to be scrolled down.
          */
         function scrollDown(obj) {
             $(obj).scrollTop(obj.scrollHeight);
@@ -18,7 +19,8 @@ define(["bootstrap", "datatable", "datatables-bootstrap", "runs/detailView", "jq
          * Turn tableElement into dataTable to display runs.
          *
          * Returns the created table.
-         * @param tableElement DOM element representing the <table>
+         *
+         * @param {DOMNode} tableElement - The <table> DOM element representing the table
          * @type {{table: DataTable, reload: function, initTable: function, queryFilter: QueryFiltersDto}}
          */
         var createRunTable = {};
@@ -43,8 +45,9 @@ define(["bootstrap", "datatable", "datatables-bootstrap", "runs/detailView", "jq
         createRunTable.queryFilter = {type: "and", filters: []};
 
         /**
-         * Initialize DataTable for given element
-         * @param tableElement HTML Table Element
+         * Initialize DataTable for given element.
+         *
+         * @param {DOMNode} tableElement - HTML <table> for placing the DataTable.
          */
         createRunTable.initTable = function (tableElement) {
             var jqRuns = $(tableElement);

sacredboard/static/scripts/runs/viewModel.js

@@ -1,14 +1,10 @@
 "use strict";
+/**
+ * The view model for the list of runs.
+ *
+ * @module runs/viewModel
+ */
 define(["knockout", "runs/filters/queryFilters", "runs/filters/queryFilter", "runs/filters", "runs/runTable"],
-    /**
-     *
-     * @param ko
-     * @param QueryFilters
-     * @param QueryFilter
-     * @param filters
-     * @param runTable
-     * @returns 
-     */
     function (ko, QueryFilters, QueryFilter, filters, runTable) {
         //Additionaly requires runTable
         ko.options.deferUpdates = true;
@@ -50,26 +46,50 @@ define(["knockout", "runs/filters/queryFilters", "runs/filters/queryFilter", "ru
 
             /**
              * Transform the curent filters to their Data Transfer Object.
-             * @returns {QueryFilterDto}
+             *
+             * @returns {QueryFilterDto} The object to be passed to the Sacredboard Web API.
              */
             getQueryFilterDto: function () {
                 return this.queryFilters().toDto();
             },
+            /**
+             * @callback listenerCallback
+             */
+            /**
+             * Subscribe to changes in the list of applied filters.
+             *
+             * @param {listenerCallback} listener - The listener function.
+             */
             subscribe: function (listener) {
                 this.queryFilters().filters.subscribe(listener);
             },
 
+            /**
+             * Reload the whole table from the backend.
+             */
             reloadTable: function () {
                 runTable.reload();
             },
 
+            /**
+             * Bind the view model to the view.
+             * Should be called after {@link module:runs/viewModel.initialize}.
+             */
             bind: function () {
                 ko.applyBindings(this);
             },
 
+            /**
+             * Initialize the view model and the table of runs.
+             *
+             * Do not forget to call {@link bind} after that.
+             *
+             * @param {DOMNode|string} runTableSelector - The HTML <table> element or its selector (e.g. '#run-table')
+             * for the list of runs.
+             */
             initialize: function (runTableSelector) {
                 /* By default, runs any state are displayed.
-                 Add them to the statusFilters.
+                 Add them to the statusFilters.q
                  */
                 for (var key in this.predefinedFilters) {
                     this.statusFilters.addFilter(this.predefinedFilters[key]);

sacredboard/static/scripts/tests/test_filters.js

@@ -1,9 +1,5 @@
 /*global QUnit*/ //for eslint to ignore missing QUnit
 define(["runs/filters/queryFilter"],
-    /**
-     *
-     * @param {QueryFilter} QueryFilter
-     */
     function (QueryFilter) {
         QUnit.module("QueryFilter");