Merge pull request #261 from rquinio/doc/missing-jsdoc

Add some missing API documentations

Author: trotttrotttrott

grafonnet/alertlist.libsonnet

@@ -1,6 +1,19 @@
 {
   /**
+   * Creates an [Alert list panel](https://grafana.com/docs/grafana/latest/panels/visualizations/alert-list-panel/)
+   *
    * @name alertlist.new
+   *
+   * @param title (default `''`)
+   * @param span (optional)
+   * @param show (default `'current'`) Whether the panel should display the current alert state or recent alert state changes.
+   * @param limit (default `10`) Sets the maximum number of alerts to list.
+   * @param sortOrder (default `'1'`) '1': alerting, '2': no_data, '3': pending, '4': ok, '5': paused
+   * @param stateFilter (optional)
+   * @param onlyAlertsOnDashboard (optional) Shows alerts only from the dashboard the alert list is in
+   * @param transparent (optional) Whether to display the panel without a background
+   * @param description (optional)
+   * @param datasource (optional)
    */
   new(
     title='',

grafonnet/bar_gauge_panel.libsonnet

@@ -5,10 +5,10 @@
    * @name barGaugePanel.new
    *
    * @param title Panel title.
-   * @param description Panel description.
-   * @param datasource Panel datasource.
-   * @param unit The unit of the data.
-   * @param thresholds An array of threashold values.
+   * @param description (optional) Panel description.
+   * @param datasource (optional) Panel datasource.
+   * @param unit (optional) The unit of the data.
+   * @param thresholds (optional) An array of threashold values.
    *
    * @method addTarget(target) Adds a target object.
    * @method addTargets(targets) Adds an array of targets.

grafonnet/cloudwatch.libsonnet

@@ -1,18 +1,18 @@
 {
   /**
-   * Return a CloudWatch Target
+   * Creates a [CloudWatch target](https://grafana.com/docs/grafana/latest/features/datasources/cloudwatch/)
    *
    * @name cloudwatch.target
    *
    * @param region
    * @param namespace
    * @param metric
-   * @param datasource
-   * @param statistic
-   * @param alias
-   * @param highResolution
-   * @param period
-   * @param dimensions
+   * @param datasource (optional)
+   * @param statistic (default: `'Average'`)
+   * @param alias (optional)
+   * @param highResolution (default: `false`)
+   * @param period (default: `'1m'`)
+   * @param dimensions (optional)
 
    * @return Panel target
    */

grafonnet/dashboard.libsonnet

@@ -2,7 +2,34 @@ local timepickerlib = import 'timepicker.libsonnet';
 
 {
   /**
+   * Creates a [dashboard](https://grafana.com/docs/grafana/latest/features/dashboard/dashboards/)
+   *
    * @name dashboard.new
+   *
+   * @param title The title of the dashboard
+   * @param editable (default: `false`) Whether the dashboard is editable via Grafana UI.
+   * @param style (default: `'dark'`) Theme of dashboard, `'dark'` or `'light'`
+   * @param tags (optional) Array of tags associated to the dashboard, e.g.`['tag1','tag2']`
+   * @param time_from (default: `'now-6h'`)
+   * @param time_to (default: `'now'`)
+   * @param timezone (default: `'browser'`) Timezone of the dashboard, `'utc'` or `'browser'`
+   * @param refresh (default: `''`) Auto-refresh interval, e.g. `'30s'`
+   * @param timepicker (optional) See timepicker API
+   * @param graphTooltip (default: `'default'`) `'default'` : no shared crosshair or tooltip (0), `'shared_crosshair'`: shared crosshair (1), `'shared_tooltip'`: shared crosshair AND shared tooltip (2)
+   * @param hideControls (default: `false`)
+   * @param schemaVersion (default: `14`) Version of the Grafana JSON schema, incremented each time an update brings changes. `26` for Grafana 7.1.5, `22` for Grafana 6.7.4, `16` for Grafana 5.4.5, `14` for Grafana 4.6.3. etc.
+   * @param uid (default: `''`) Unique dashboard identifier as a string (8-40), that can be chosen by users. Used to identify a dashboard to update when using Grafana REST API.
+   * @param description (optional)
+   *
+   * @method addTemplate(template) Add a template variable
+   * @method addTemplates(templates) Adds an array of template variables
+   * @method addAnnotation(annotation) Add an [annotation](https://grafana.com/docs/grafana/latest/dashboards/annotations/)
+   * @method addPanel(panel,gridPos) Appends a panel, with an optional grid position in grid coordinates, e.g. `gridPos={'x':0, 'y':0, 'w':12, 'h': 9}`
+   * @method addPanels(panels) Appends an array of panels
+   * @method addLink(link) Adds a [dashboard link](https://grafana.com/docs/grafana/latest/linking/dashboard-links/)
+   * @method addRequired(type, name, id, version)
+   * @method addInput(name, label, type, pluginId, pluginName, description, value)
+   * @method addRow(row) Adds a row. This is the legacy row concept from Grafana < 5, when rows were needed for layout. Rows should now be added via `addPanel`.
    */
   new(
     title,

grafonnet/dashlist.libsonnet

@@ -1,19 +1,19 @@
 {
   /**
-   * Returns a new dashlist panel that can be added in a row.
+   * Creates a [dashlist panel](https://grafana.com/docs/grafana/latest/panels/visualizations/dashboard-list-panel/).
    * It requires the dashlist panel plugin in grafana, which is built-in.
    *
    * @name dashlist.new
    *
    * @param title The title of the dashlist panel.
-   * @param description Description of the panel
-   * @param query Query to search by
-   * @param tags Tag(s) to search by
-   * @param recent Displays recently viewed dashboards
-   * @param search Description of the panel
-   * @param starred Displays starred dashboards
-   * @param headings Chosen list selection(starred, recently Viewed, search) is shown as a heading
-   * @param limit Set maximum items in a list
+   * @param description (optional) Description of the panel
+   * @param query (optional) Query to search by
+   * @param tags (optional) Array of tag(s) to search by
+   * @param recent (default `true`) Displays recently viewed dashboards
+   * @param search (default `false`) Description of the panel
+   * @param starred (default `false`) Displays starred dashboards
+   * @param headings (default `true`) Chosen list selection(starred, recently Viewed, search) is shown as a heading
+   * @param limit (default `10`) Set maximum items in a list
    * @return A json that represents a dashlist panel
    */
   new(

grafonnet/elasticsearch.libsonnet

@@ -1,6 +1,16 @@
 {
   /**
+   * Creates an [Elasticsearch target](https://grafana.com/docs/grafana/latest/features/datasources/elasticsearch/)
+   *
    * @name elasticsearch.target
+   *
+   * @param query
+   * @param timeField
+   * @param id (optional)
+   * @param datasource (optional)
+   * @param metrics (optional)
+   * @param bucketAggs (optional)
+   * @param alias (optional)
    */
   target(
     query,

grafonnet/gauge_panel.libsonnet

@@ -5,30 +5,30 @@
    * @name gaugePanel.new
    *
    * @param title Panel title.
-   * @param description Panel description.
-   * @param transparent Whether to display the panel without a background.
-   * @param datasource Panel datasource.
-   * @param allValues Show all values instead of reducing to one.
-   * @param valueLimit Limit of values in all values mode.
-   * @param reducerFunction Function to use to reduce values to when using single value.
-   * @param fields Fields that should be included in the panel.
-   * @param showThresholdLabels Render the threshold values around the gauge bar.
-   * @param showThresholdMarkers Render the thresholds as an outer bar.
-   * @param unit Panel unit field option.
-   * @param min Leave empty to calculate based on all values.
-   * @param max Leave empty to calculate based on all values.
+   * @param description (optional) Panel description.
+   * @param transparent (default `false`) Whether to display the panel without a background.
+   * @param datasource (optional) Panel datasource.
+   * @param allValues (default `false`) Show all values instead of reducing to one.
+   * @param valueLimit (optional) Limit of values in all values mode.
+   * @param reducerFunction (default `'mean'`) Function to use to reduce values to when using single value.
+   * @param fields (default `''`) Fields that should be included in the panel.
+   * @param showThresholdLabels (default `false`) Render the threshold values around the gauge bar.
+   * @param showThresholdMarkers (default `true`) Render the thresholds as an outer bar.
+   * @param unit (default `'percent'`) Panel unit field option.
+   * @param min (optional) Leave empty to calculate based on all values.
+   * @param max (optional) Leave empty to calculate based on all values.
    * @param decimals Number of decimal places to show.
    * @param displayName Change the field or series name.
-   * @param noValue What to show when there is no value.
-   * @param thresholdsMode 'absolute' or 'percentage'.
-   * @param repeat Name of variable that should be used to repeat this panel.
-   * @param repeatDirection 'h' for horizontal or 'v' for vertical.
-   * @param repeatMaxPerRow Maximum panels per row in repeat mode.
-   * @param pluginVersion Plugin version the panel should be modeled for. This has been tested with the default, '7', and '6.7'.
+   * @param noValue (optional) What to show when there is no value.
+   * @param thresholdsMode (default `'absolute'`) 'absolute' or 'percentage'.
+   * @param repeat (optional) Name of variable that should be used to repeat this panel.
+   * @param repeatDirection (default `'h'`) 'h' for horizontal or 'v' for vertical.
+   * @param repeatMaxPerRow (optional) Maximum panels per row in repeat mode.
+   * @param pluginVersion (default `'7'`) Plugin version the panel should be modeled for. This has been tested with the default, '7', and '6.7'.
    *
    * @method addTarget(target) Adds a target object.
    * @method addTargets(targets) Adds an array of targets.
-   * @method addLink(link) Adds a link. Argument format: `{ title: 'Link Title', url: 'https://...', targetBlank: true }`.
+   * @method addLink(link) Adds a [panel link](https://grafana.com/docs/grafana/latest/linking/panel-links/). Argument format: `{ title: 'Link Title', url: 'https://...', targetBlank: true }`.
    * @method addLinks(links) Adds an array of links.
    * @method addThreshold(step) Adds a threshold step. Argument format: `{ color: 'green', value: 0 }`.
    * @method addThresholds(steps) Adds an array of threshold steps.

grafonnet/graph_panel.libsonnet

@@ -1,60 +1,68 @@
 {
   /**
-   * Returns a new graph panel that can be added in a row.
+   * Creates a [graph panel](https://grafana.com/docs/grafana/latest/panels/visualizations/graph-panel/).
    * It requires the graph panel plugin in grafana, which is built-in.
    *
    * @name graphPanel.new
    *
    * @param title The title of the graph panel.
-   * @param span Width of the panel
-   * @param datasource Datasource
-   * @param fill Fill, integer from 0 to 10
-   * @param linewidth Line Width, integer from 0 to 10
-   * @param decimals Override automatic decimal precision for legend and tooltip. If null, not added to the json output.
-   * @param decimalsY1 Override automatic decimal precision for the first Y axis. If null, use decimals parameter.
-   * @param decimalsY2 Override automatic decimal precision for the second Y axis. If null, use decimals parameter.
-   * @param min_span Min span
-   * @param format Unit of the Y axes
-   * @param formatY1 Unit of the first Y axis
-   * @param formatY2 Unit of the second Y axis
-   * @param min Min of the Y axes
-   * @param max Max of the Y axes
-   * @param labelY1 Label of the first Y axis
-   * @param labelY2 Label of the second Y axis
-   * @param x_axis_mode X axis mode, one of [time, series, histogram]
-   * @param x_axis_values Chosen value of series, one of [avg, min, max, total, count]
-   * @param x_axis_buckets restricts the x axis to this amount of buckets
-   * @param x_axis_min restricts the x axis to display from this value if supplied
-   * @param x_axis_max restricts the x axis to display up to this value if supplied
-   * @param lines Display lines, boolean
-   * @param points Display points, boolean
-   * @param pointradius Radius of the points, allowed values are 0.5 or [1 ... 10] with step 1
-   * @param bars Display bars, boolean
-   * @param staircase Display line as staircase, boolean
-   * @param dashes Display line as dashes
-   * @param stack Stack values
-   * @param repeat Variable used to repeat the graph panel
-   * @param legend_show Show legend
-   * @param legend_values Show values in legend
-   * @param legend_min Show min in legend
-   * @param legend_max Show max in legend
-   * @param legend_current Show current in legend
-   * @param legend_total Show total in legend
-   * @param legend_avg Show average in legend
-   * @param legend_alignAsTable Show legend as table
-   * @param legend_rightSide Show legend to the right
-   * @param legend_sideWidth Legend width
-   * @param legend_sort Sort order of legend
-   * @param legend_sortDesc Sort legend descending
-   * @param aliasColors Define color mappings for graphs
-   * @param thresholds Configuration of graph thresholds
-   * @param logBase1Y Value of logarithm base of the first Y axis
-   * @param logBase2Y Value of logarithm base of the second Y axis
-   * @param transparent Boolean (default: false) If set to true the panel will be transparent
-   * @param value_type Type of tooltip value
-   * @param shared_tooltip Boolean Allow to group or spit tooltips on mouseover within a chart
-   * @param percentage Boolean (defaut: false) show as percentages
-   * @return A json that represents a graph panel
+   * @param description (optional) The description of the panel
+   * @param span (optional) Width of the panel
+   * @param datasource (optional) Datasource
+   * @param fill (default `1`) , integer from 0 to 10
+   * @param linewidth (default `1`) Line Width, integer from 0 to 10
+   * @param decimals (optional) Override automatic decimal precision for legend and tooltip. If null, not added to the json output.
+   * @param decimalsY1 (optional) Override automatic decimal precision for the first Y axis. If null, use decimals parameter.
+   * @param decimalsY2 (optional) Override automatic decimal precision for the second Y axis. If null, use decimals parameter.
+   * @param min_span (optional) Min span
+   * @param format (default `short`) Unit of the Y axes
+   * @param formatY1 (optional) Unit of the first Y axis
+   * @param formatY2 (optional) Unit of the second Y axis
+   * @param min (optional) Min of the Y axes
+   * @param max (optional) Max of the Y axes
+   * @param labelY1 (optional) Label of the first Y axis
+   * @param labelY2 (optional) Label of the second Y axis
+   * @param x_axis_mode (default `'time'`) X axis mode, one of [time, series, histogram]
+   * @param x_axis_values (default `'total'`) Chosen value of series, one of [avg, min, max, total, count]
+   * @param x_axis_buckets (optional) Restricts the x axis to this amount of buckets
+   * @param x_axis_min (optional) Restricts the x axis to display from this value if supplied
+   * @param x_axis_max (optional) Restricts the x axis to display up to this value if supplied
+   * @param lines (default `true`) Display lines
+   * @param points (default `false`) Display points
+   * @param pointradius (default `5`) Radius of the points, allowed values are 0.5 or [1 ... 10] with step 1
+   * @param bars (default `false`) Display bars
+   * @param staircase (default `false`) Display line as staircase
+   * @param dashes (default `false`) Display line as dashes
+   * @param stack (default `false`) Whether to stack values
+   * @param repeat (optional) Name of variable that should be used to repeat this panel.
+   * @param repeatDirection (default `'h'`) 'h' for horizontal or 'v' for vertical.
+   * @param legend_show (default `true`) Show legend
+   * @param legend_values (default `false`) Show values in legend
+   * @param legend_min (default `false`) Show min in legend
+   * @param legend_max (default `false`) Show max in legend
+   * @param legend_current (default `false`) Show current in legend
+   * @param legend_total (default `false`) Show total in legend
+   * @param legend_avg (default `false`) Show average in legend
+   * @param legend_alignAsTable (default `false`) Show legend as table
+   * @param legend_rightSide (default `false`) Show legend to the right
+   * @param legend_sideWidth (optional) Legend width
+   * @param legend_sort (optional) Sort order of legend
+   * @param legend_sortDesc (optional) Sort legend descending
+   * @param aliasColors (optional) Define color mappings for graphs
+   * @param thresholds (optional) An array of graph thresholds
+   * @param logBase1Y (default `1`) Value of logarithm base of the first Y axis
+   * @param logBase2Y (default `1`) Value of logarithm base of the second Y axis
+   * @param transparent (default `false`) Whether to display the panel without a background.
+   * @param value_type (default `'individual'`) Type of tooltip value
+   * @param shared_tooltip (default `true`) Allow to group or spit tooltips on mouseover within a chart
+   * @param percentage (defaut: false) show as percentages
+   *
+   * @method addTarget(target) Adds a target object.
+   * @method addTargets(targets) Adds an array of targets.
+   * @method addSeriesOverride(override)
+   * @method addYaxis(format,min,max,label,show,logBase,decimals) Adds a Y axis to the graph
+   * @method addAlert(alert) Adds an alert
+   * @method addLink(link) Adds a [panel link](https://grafana.com/docs/grafana/latest/linking/panel-links/)
    */
   new(
     title,

grafonnet/graphite.libsonnet

@@ -1,14 +1,14 @@
 {
   /**
-   * Return an Graphite Target
+   * Creates a [Graphite target](https://grafana.com/docs/grafana/latest/features/datasources/graphite/)
    *
    * @name graphite.target
    *
    * @param target Graphite Query. Nested queries are possible by adding the query reference (refId).
-   * @param targetFull Expanding the @target. Used in nested queries.
-   * @param hide Disable query on graph.
-   * @param textEditor Enable raw query mode.
-   * @param datasource Datasource.
+   * @param targetFull (optional) Expanding the @target. Used in nested queries.
+   * @param hide (default `false`) Disable query on graph.
+   * @param textEditor (default `false`) Enable raw query mode.
+   * @param datasource (optional) Datasource.
 
    * @return Panel target
    */