diff --git a/.eslintrc.js b/.eslintrc.js index fb5d15f..8876979 100644 --- a/.eslintrc.js +++ b/.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, diff --git a/sacredboard/static/scripts/enquotedStringOrNumberValidator.js b/sacredboard/static/scripts/enquotedStringOrNumberValidator.js index 205eda1..3283b5d 100644 --- a/sacredboard/static/scripts/enquotedStringOrNumberValidator.js +++ b/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) { diff --git a/sacredboard/static/scripts/escapeHtml.js b/sacredboard/static/scripts/escapeHtml.js index 569cb52..3ed8188 100644 --- a/sacredboard/static/scripts/escapeHtml.js +++ b/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; diff --git a/sacredboard/static/scripts/runs/detailView.js b/sacredboard/static/scripts/runs/detailView.js index 606ebdb..406ddfc 100644 --- a/sacredboard/static/scripts/runs/detailView.js +++ b/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/). + * @returns {string} - HTML representation of the detail. */ function generateDetailView(run) { // `run` is the original data object for the row diff --git a/sacredboard/static/scripts/runs/dictionaryBrowser/DictEntry.js b/sacredboard/static/scripts/runs/dictionaryBrowser/DictEntry.js index 18d96d7..90142cb 100644 --- a/sacredboard/static/scripts/runs/dictionaryBrowser/DictEntry.js +++ b/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 Array. + * DictEntry("me", ["hello", "world"]).getChildren() + * // returns * [DictEntry("0", "hello"), DictEntry("1", "world")] * - * DictEntry("me", {"key1": "value1", "key2": ["hello", "world"]}).getChildren() returns + * @example Object. + * DictEntry("me", {"key1": "value1", "key2": ["hello", "world"]}).getChildren() + * // returns * [DictEntry("key1", "value1"), DictEntry("key2", ["hello", "world"])] * - * DictEntry("me", "string").getChildren() returns - * [] + * @example Native type.. + * 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 Native value. + * DictEntry("hello", "world").getDisplayValue() + * // returns "world" + * + * @example Object. + * DictEntry("hello", {"key": "value"}).getDisplayValue() + * // returns "{...}" + * + * @example Array. + * DictEntry("hello", [1,2,3]).getDisplayValue() + * // returns "[1, 2, 3]" * * @returns {string} String representation of the value. */ diff --git a/sacredboard/static/scripts/runs/filters/queryFilter.js b/sacredboard/static/scripts/runs/filters/queryFilter.js index fbf4eba..7d29176 100644 --- a/sacredboard/static/scripts/runs/filters/queryFilter.js +++ b/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,7 +104,8 @@ 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()); @@ -111,12 +113,14 @@ define(["knockout", "enquotedStringOrNumberValidator"], /** * 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 { diff --git a/sacredboard/static/scripts/runs/filters/queryFilters.js b/sacredboard/static/scripts/runs/filters/queryFilters.js index 81e9375..f1041e3 100644 --- a/sacredboard/static/scripts/runs/filters/queryFilters.js +++ b/sacredboard/static/scripts/runs/filters/queryFilters.js @@ -5,7 +5,7 @@ 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. * 

          * new QueryFilters("or", [ new QueryFilter('X', '==', 'hello'),
          *                          new QueryFilters('and', [
@@ -13,16 +13,21 @@ define(["knockout", "jquery"],
          *                              new QueryFilter('B', '<', 10)
          *                                          ])
          *                 ]);
-         *
- * @param {String} type - either 'and' or 'or'. Default: 'and' - * @param {QueryFilter[]|QueryFilters[]} filters + * . + * + * @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 { diff --git a/sacredboard/static/scripts/runs/runTable.js b/sacredboard/static/scripts/runs/runTable.js index 1cfc433..a811095 100644 --- a/sacredboard/static/scripts/runs/runTable.js +++ b/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 + * + * @param {DOMNode} tableElement - The
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
for placing the DataTable. */ createRunTable.initTable = function (tableElement) { var jqRuns = $(tableElement); diff --git a/sacredboard/static/scripts/runs/viewModel.js b/sacredboard/static/scripts/runs/viewModel.js index aff9dc2..c0993fc 100644 --- a/sacredboard/static/scripts/runs/viewModel.js +++ b/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
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]); diff --git a/sacredboard/static/scripts/tests/test_filters.js b/sacredboard/static/scripts/tests/test_filters.js index 895241f..059c76b 100644 --- a/sacredboard/static/scripts/tests/test_filters.js +++ b/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");