Merge pull request #71 from NASA-AMMOS/issue47

Issue #47 - Add GUI widget docs

ait/gui/static/js/ait/gui/Clock.js

@@ -21,14 +21,35 @@ import * as format from 'ait/format'
  * AIT Clock UI Widget
  *
  * The AIT Clock UI Widget displays a clock with date and time that
- * updates every second.  The display is configurable with at
- * initialization time or by clicking on specific parts of the time.
+ * updates every second.  The display is configurable at initialization 
+ * time or by clicking on specific parts of the time / date display.
  *
  * Configurable / Toggleable options include:
  *
  *   - 12-hour or 24-hour time
  *   - Date (month and day) or Day of Year (DOY)
- *   - UTC or localtime
+ *   - GPS, UTC, or localtime
+ *
+ * **Optional Attributes:**
+ *
+ * h24
+ *   Display clock in 24 hour time instead of 12 hour time. (default: true)
+ *
+ * gps
+ *   Display clock in GPS time. This value overrides UTC time display
+ *   if both are true. (default: true)
+ *
+ * utc
+ *   Display clock in UTC time. (defaut: false)
+ *
+ * doy
+ *   Display date as Day of Year. (default: false)
+ *
+ * @example
+ * <ait-clock></ait-clock>
+ *
+ * @example
+ * <ait-clock h24='true' utc='true'></ait-clock>
  */
 const Clock =
 {

ait/gui/static/js/ait/gui/Command.js

@@ -25,6 +25,14 @@ import values from 'lodash/values'
 var typeahead = require('typeahead.js/dist/typeahead.jquery');
 var Bloodhound = require('typeahead.js/dist/bloodhound');
 
+/**
+ * Command History file display component
+ *
+ * Displays command history data and auto-refreshes on receipt of
+ * **cmd:hist** or **seq:done** events.
+ *
+ * @example <ait-command-history></ait-command-history>
+ */
 const CommandHistory = {
     _cmdHistory: null,
 
@@ -67,6 +75,15 @@ const CommandHistory = {
     }
 }
 
+/**
+ * Search input field for locating, verifying, and submitting commands.
+ *
+ * Searches over the command dictionary and command history. The component
+ * will be automatically disabled when a sequence is being run. Responds to
+ * the **cmd:hist**, **seq:exec**, **seq:done**, and **seq:err** events.
+ *
+ * @example <ait-command-input></ait-command-input>
+ */
 const CommandInput = {
     _cntrl_toggled: false,
     _cmding_disabled: false,
@@ -293,6 +310,14 @@ let CommandSelectionData = {
     activeCommand: null,
 }
 
+/**
+ * Command Browser Search sub-component
+ *
+ * Handles command searching / filtering for the Command Browser component.
+ * Displays commands by subsystem and filters choices based on user input.
+ *
+ * @example <ait-command-search></ait-command-search>
+ */
 const CommandSearch = {
     groupedCommands: {},
     commandFilter: '',
@@ -440,8 +465,21 @@ const CommandSearch = {
 }
 
 /**
- * Handle the configuration of command arguments for the currently select
- * command (specified via CommandSelectionData.activeCommand)
+ * Command Browser Configure sub-component
+ *
+ * Handles command configuration, validation, and submission. This command to be
+ * configured is set in *CommandSelectionData.activeCommand*.
+ *
+ * **CommandSelectionData.activeCommand Format:**
+ *
+ * .. code::
+ *
+ *    {
+ *        name: <command name>,
+ *        desc: <command description>
+ *    }
+ *
+ * @example <ait-command-configure></ait-command-configure>
  */
 const CommandConfigure = {
     _cmding_disabled: false,

ait/gui/static/js/ait/gui/Field.js

@@ -21,6 +21,34 @@ import * as strftime from 'strftime'
 import { CommandDefinition } from '../cmd.js'
 import { EVRDefinition }     from '../evr.js'
 
+/**
+ * Display a given packet's telemetry point value in the display.
+ *
+ * **Required Attributes:**
+ *
+ * packet
+ *   The packet name where the telemetry point is located
+ *
+ * name
+ *   The name of the field in the packet to display
+ *
+ * **Optional Attributes:**
+ *
+ * raw
+ *   Toggle whether the field should be displayed as a raw value instead
+ *   of the default of displaying a DN-to-EU value. (default: false)
+ *
+ * disable-tlm-popover
+ *   Toggle whether a popover should be placed on the field value displaying
+ *   telemetry dictionary information for the displayed field. (default: false)
+ *
+ * format
+ *   Format string to use when displaying the value. The value for the field
+ *   is passed through either strftime or sprintf depending on type if format
+ *   is specified. If the field is an array type the format attribute is
+ *   ignored. By default, a field is displayed as a 5 digit precision number.
+ *   (default: none)
+ */
 const Field =
 {
     _limitOut: false,

ait/gui/static/js/ait/gui/Messages.js

@@ -18,6 +18,13 @@ import m from 'mithril'
 import * as format from 'ait/format'
 
 
+/**
+ *
+ * Component for displaying log messages
+ *
+ * @example <ait-messages></ait-messages>
+ *
+ */
 const Messages =
 {
     _messages: [],

ait/gui/static/js/ait/gui/Plot.js

@@ -236,6 +236,107 @@ class HighchartsBackend
 }
 
 
+/**
+ *
+ * Display a plot of telemetry data
+ *
+ * Plot configuration can be done with a number of children tags and
+ * attributes. A plot must have at least one **ait-plot-series** child
+ * so that it has something to plot
+ *
+ * The Plot component supports graphing with Dygraphs (default) and
+ * HighCharts. If you want to use HighCharts instead of Dygraphs you
+ * need to include the Highcharts JS file in your page. If the
+ * *window.Highcharts* object is defined then Highcharts will be used.
+ *
+ * **Optional Attributes:**
+ *
+ * redraw-frequency
+ *   The frequency, in seconds, that the plot should be redrawn. (default: 10)
+ *
+ * redraw-frequency-variation
+ *   Toggle whether plot redraw frequency should be affected by random
+ *   variation. If enabled, the redraw frequency of the plot will vary
+ *   by [redraw-frequency-var-min, redraw-frequency-variation-max] seconds each
+ *   refresh. This is useful if you have a large number of plots and need
+ *   to avoid all of them attempting to redraw at the same time.
+ *   (default: false)
+ *
+ * redraw-frequency-variation-min (-2)
+ *   The minimum variation in seconds to add to the redraw frequency
+ *
+ * redraw-frequency-variation-max (2)
+ *   The maximum variation in seconds to add to the redraw frequency
+ *
+ * **ait-plot-series:**
+ *
+ * Configure the series of data that should be plotted. At least 1 series of
+ * data is required for the plot to function.
+ *
+ * Required attributes:
+ *
+ * packet
+ *   The packet in which the series telemetry point is located.
+ *
+ * field
+ *   The name of the field in the packet that defines this series.
+ *
+ * Optional attributes:
+ * 
+ * type
+ *   The type of series being displayed. This is not relevant for all plot
+ *   backends. For instance, Highcharts would use this to define the type
+ *   of plot to show whereas Dygraphs does not support this value. If you're
+ *   using Highcharts this attribute is required and would most commonly be
+ *   set to **line**.
+ *
+ * .. code:: Javascript
+ *
+ *    <ait-plot-series packet="1553_HS_Packet" field="Voltage_A"></ait-plot-series>
+ *
+ * **ait-plot-config:**
+ *
+ * Allows the passing of a JSON object for configuration of the current
+ * backend into the plot. Any setting that is valid for the backend
+ * being used can be included in the JSON object. Please consult the relevant
+ * backend's documentation for information on valid settings.
+ *
+ * .. code::
+ *
+ *    <ait-plot-config>
+ *      {
+ *         "title": "Plot title",
+ *         "xlabel": "X label",
+ *         "ylabel": "Y label"  
+ *      }
+ *    </ait-plot-config>
+ *
+ * **ait-plot-time:**
+ *
+ * Facilitates setting the name of a telemetry field defining the timestamp
+ * used when plotting data. If the evaluation of the specified telemetry field
+ * does not result in a number of Date() object the current time is used
+ * instead. If no **ait-plot-time** tag is specified the current time
+ * is used.
+ *
+ * .. code:: Javascript
+ *
+ *    <ait-plot-time packet="1553_HS_Packet" field="FSWTimeField"></ait-plot-time>
+ *
+ * @example
+ * <ait-plot redraw-frequency="1">
+ *   <ait-plot-config>
+ *     {
+ *       "width": 600,
+ *       "height": 300
+ *     }
+ *   </ait-plot-config>
+ *   <ait-plot-series packet="1553_HS_Packet" name="Voltage_A"></ait-plot-series>
+ *   <ait-plot-series packet="1553_HS_Packet" name="Voltage_B"></ait-plot-series>
+ *   <ait-plot-series packet="1553_HS_Packet" name="Voltage_C"></ait-plot-series>
+ *   <ait-plot-series packet="1553_HS_Packet" name="Voltage_D"></ait-plot-series>
+ * </ait-plot> 
+ */
 const Plot =
 {
     /**
@@ -264,7 +365,7 @@ const Plot =
 
 
     /**
-     * Process tag: `<ait-plot-series type="..." caption="..." ...>`.
+     * Process tag: `<ait-plot-series type="..." ...>`.
      */
     processTagSeries (vnode) {
         const name   = vnode.attrs.name

ait/gui/static/js/ait/gui/Query.js

@@ -1,32 +1,37 @@
 import map from 'lodash/map'
 
-/*
- * TelemetryQuery Component
- *
+/**
  * Generate and run queries against captured telemetry data in PCAP files and
  * retrieve a CSV of the resulting data.
  *
- * Configuration attributes:
- *      data-dir (optional): The data directory key specifying which directory
- *          should be used when gathering telemetry data PCAPs.
+ * **Optional Attributes:**
+ *
+ *  data-dir
+ *    The data directory key specifying which directory should be used when
+ *    gathering telemetry data PCAPs.
  *
- *      packet (optional): The name of the packet definition in the telemetry
- *          dictionary from which fields will be selected for the query.
+ *  packet
+ *    The name of the packet definition in the telemetry dictionary from which
+ *    fields will be selected for the query.
  *
- *      time-field (optional): The telemetry field name that will be used as the
- *          time baseline in the query.
+ *  time-field
+ *    The telemetry field name that will be used as the time baseline in the
+ *    query.
  *
- *      Note, specifying one or more of these optional attributes will remove
- *      the corresponding input field from the UI.
+ *  .. note::
  *
- * Example Tags:
- *  <ait-telemetryquery></ait-telemetryquery>
+ *     Specifying one or more of these optional attributes will remove the
+ *     corresponding input field from the UI.
  *
- *  <ait-telemetryquery data-dir='/tmp/fakepcapdir'
- *                        packet='1553_EHS_Packet'
- *                        time-field='time_coarse'>
- *  </ait-telemetryquery>
+ * @example
+ * <ait-telemetryquery></ait-telemetryquery>
  *
+ * @example
+ * <ait-telemetryquery
+ *   data-dir='/tmp/fakepcapdir'
+ *   packet='1553_EHS_Packet'
+ *   time-field='time_coarse'>
+ * </ait-telemetryquery>
  */
 const TelemetryQuery = {
     _data_paths: {},

ait/gui/static/js/ait/gui/Script.js

@@ -485,7 +485,10 @@ const ScriptNotification = {
 
 
 /**
- * Manages global script states and component layout
+ * Script display, state management, and execution control.
+ *
+ * @example
+ * <ait-scripts></ait-scripts>
  */
 const Scripts = {
     oninit(vnode) {

ait/gui/static/js/ait/gui/Search.js

@@ -24,6 +24,45 @@ import * as format from 'ait/format'
 import Field from './Field'
 import Clock from './Clock'
 
+/**
+ * Search for a Packets's telemetry fields by name and display dictionary data
+ * and data snapshot of selected value in a modal. 
+ *
+ * Requires that ait-modal is included in the page for modal functionality
+ * to work. Default styling via the display-border and invert-colors attributes
+ * is set for display as part of the default Bootstrap navbar. You should consider
+ * adjusting these settings if you plan to display the component in a different part
+ * of the UI.
+ *
+ * **Required Attributes:**
+ *
+ * packet
+ *   The name of the packet in the telemetry dictionary that should be searched for fields
+ *
+ * **Optional Attributes:**
+ *
+ * result-count
+ *   The number of results to show when autocompleting (default: 20)
+ *
+ * display-border
+ *   Adds the 'no-borders' css class to the component display. This drops borders
+ *   from the displayed input field. (default: false)
+ *
+ * invert-colors
+ *   Adds the 'inverse-colors' class to the component display. When included
+ *   this displays the component as a black background with white
+ *   foreground / icons when unfocused. (default: true)
+ *
+ * @example
+ * <ait-mnemonic-search packet="1553_HS_Packet"></ait-mnemonic-search>
+ *
+ * @example
+ * <ait-mnemonic-search packet="1553_HS_Packet"
+ *     result-count="10"
+ *     display-border="true"
+ *     invert-colors="false">
+ * </ait-mnemonic-search>
+ */
 const MnemonicSearch = {
     _packet: null,
     _selection: null,