More documentation for plotly helper

src/core/js/ext_bottom_line.js

@@ -2,8 +2,8 @@
  * ** header v3.0
  * This file is a part of the CaosDB Project.
  *
- * Copyright (C) 2019 IndiScale GmbH (info@indiscale.com)
- * Copyright (C) 2019 Timm Fitschen (t.fitschen@indiscale.com)
+ * Copyright (C) 2020 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2020 Timm Fitschen <t.fitschen@indiscale.com>
  *
  * This program is free software: you can redistribute it and/or modify
  * it under the terms of the GNU Affero General Public License as
@@ -26,17 +26,20 @@
 
 /**
  * Add a special section to each entity one the current page where a thumbnail,
- * a video preview or any other kind of preview for the entity is shown.
+ * a video preview or any other kind of summary for the entity is shown.
  *
  * @module ext_bottom_line
  * @version 0.1
  *
- * @requires jQuery
- * @requires logger
+ * @requires jQuery (library)
+ * @requires log (singleton from loglevel library)
+ * @requires resolve_references.is_in_viewport_vertically (funtion from ext_references.js)
+ * @requires load_config (function from caosdb.js)
+ * @requires getEntityPath (function from caosdb.js)
+ * @requires connection (module from webcaosdb.js)
  */
 var ext_bottom_line = function ($, logger, is_in_view_port, load_config, getEntityPath, connection) {
 
-
     /**
      * Check if an entity has a path attribute and one of a set of extensions.
      *
@@ -122,7 +125,7 @@ var ext_bottom_line = function ($, logger, is_in_view_port, load_config, getEnti
      *
      * @member {Creator[]}
      */
-    var _creators = [];
+    const _creators = [];
 
     /**
      * Return the preview container of the entity.
@@ -131,7 +134,7 @@ var ext_bottom_line = function ($, logger, is_in_view_port, load_config, getEnti
      * @returns {HTMLElement} the preview container or `undefined` if the entity
      *     doesn't have any.
      */
-    var get_preview_container = function (entity) {
+    const get_preview_container = function (entity) {
         return $(entity).children(`.${_css_class_preview_container}`)[0];
     }
 
@@ -152,8 +155,8 @@ var ext_bottom_line = function ($, logger, is_in_view_port, load_config, getEnti
      * @param {HTMLElement} entity - An entity in HTML Representation which
      *     must have a (deep) child with class `caosdb-f-ext_bottom_line-container`.
      */
-    var set_preview_container = function (entity, element) {
-        var preview_container = $(get_preview_container(entity));
+    const set_preview_container = function (entity, element) {
+        const preview_container = $(get_preview_container(entity));
         if (preview_container[0]) {
             preview_container.empty();
             var buttons = preview_container.siblings(`.${_css_class_preview_container_button}`);
@@ -407,7 +410,7 @@ var ext_bottom_line = function ($, logger, is_in_view_port, load_config, getEnti
      * @property {Config} [config] - an optional config. Per default, the
      *     configuration is fetched from the server.
      */
-    var init = async function (config) {
+    const init = async function (config) {
         logger.info("ext_bottom_line initialized");
 
         try {
@@ -446,20 +449,35 @@ var ext_bottom_line = function ($, logger, is_in_view_port, load_config, getEnti
  */
 var plotly_preview = function (logger, ext_bottom_line, plotly) {
 
-    var create_plot = function (data) {
+    /**
+     * Create a plot with plotly.
+     *
+     * The layout and any other plotly options are set by this function. The
+     * only parameter `data` is the `data` parameter of the `Plotly.newPlot`
+     * factory.
+     *
+     * Hence the full documentation of the `data` parameter is available at
+     * https://plotly.com/javascript/plotlyjs-function-reference/#plotlynewplot
+     *
+     *
+     * @param {object[]} data - array of objects containing the data which is
+     *     to be plotted.
+     * @returns {HTMLElement} the element which contains the plot.
+     */
+    const create_plot = function (data) {
         var div = $('<div/>')[0];
         plotly.newPlot(div, data, { margin: { t: 0}, height: 400, widht: 400 }, {responsive: true});
         return div;
     }
 
-    var resize_plots_event_handler = function (e) {
+    const resize_plots_event_handler = function (e) {
         var plots = $(e.target).find(".js-plotly-plot");
         for (let plot of plots) {
             plotly.Plots.resize(plot);
         }
     }
 
-    var init = function () {
+    const init = function () {
         window.addEventListener(ext_bottom_line.previewReadyEvent.type,
             resize_plots_event_handler, true);
         window.addEventListener(ext_bottom_line.previewShownEvent.type,
@@ -476,7 +494,7 @@ var plotly_preview = function (logger, ext_bottom_line, plotly) {
 
 // this will be replaced by require.js in the future.
 $(document).ready(function () {
-    if ("${BUILD_MODULE_NEW_MODULE}" === "ENABLED") {
+    if ("${BUILD_MODULE_EXT_BOTTOM_LINE}" === "ENABLED") {
         caosdb_modules.register(plotly_preview);
         caosdb_modules.register(ext_bottom_line);
     }