Skeleton API docs

Gruntfile.js

@@ -8,7 +8,7 @@ module.exports = function (grunt) {
     srcDir: 'src',
     destDir: 'dist',
     tempDir: 'tmp',
-    docsDir: 'docs'
+    docsDir: 'docs/'
   };
 
   // load plugins

docs/kibana/configuration/config.js.asciidoc

@@ -1,13 +1,10 @@
-
-= Kibana =
-
 == Configuration ==
 config.js is where you will find the core Kibana configuration. This file contains parameter that
 must be set before kibana is run for the first time.
 // src/config.js:1
 
 === Parameters ===
-// src/config.js:13
+// src/config.js:10
 
 ==== elasticsearch ====
 
@@ -16,17 +13,17 @@ want +http://localhost:9200+ here. Even if Kibana and Elasticsearch are on
 the same host. By default this will attempt to reach ES at the same host you have
 elasticsearch installed on. You probably want to set it to the FQDN of your
 elasticsearch host
-// src/config.js:18
+// src/config.js:15
 
 ==== kibana-int ====
 
 The default ES index to use for storing Kibana specific object
 such as stored dashboards
-// src/config.js:29
+// src/config.js:26
 
 ==== panel_name ====
 
 An array of panel modules available. Panels will only be loaded when they are defined in the
 dashboard, but this list is used in the "add panel" interface.
-// src/config.js:37
+// src/config.js:34
 

docs/kibana/index.asciidoc

@@ -0,0 +1,18 @@
+= Kibana
+
+// Why can't I have a preamble here?
+
+== Introduction
+
+Kibana is an open source (Apache Licensed), browser based analytics and search dashboard for
+ElasticSearch. Kibana is a snap to setup and start using. Written entirely in HTML and Javascript
+it requires only a plain webserver, Kibana requires no fancy server side components.
+Kibana strives to be easy to get started with, while also being flexible and powerful, just like
+Elasticsearch.
+
+include::configuration/config.js.asciidoc[]
+
+include::panels.asciidoc[]
+
+// src/app/controllers/dash.js:1
+

docs/kibana/panels.asciidoc

@@ -0,0 +1,64 @@
+[[panels]]
+= Panels
+
+[partintro]
+--
+*Kibana* dashboards are made up of blocks called +panels+. Panels are organized into rows
+and can serve many purposes, though most are designed to provide the results of a query or
+multiple queries as a visualization. Other panels may show collections of documents or
+allow you to insert instructions for your users.
+
+Panels can be configured easily via the Kibana web interface. For more advanced usage, such
+as templated or scripted dashboards, documentation of panel properties is available in this
+section. You may find settings here which are not exposed via the web interface.
+
+Each panel type has its own properties, hover there are several that are shared.
+
+// src/app/controllers/row.js:61
+
+span:: A number, 1-12, that describes the width of the panel.
+// src/app/controllers/row.js:87
+
+editable:: Enable or disable the edit button the the panel
+// src/app/controllers/row.js:91
+
+type:: The type of panel this object contains. Each panel type will require additional
+properties. See the panel types list to the right.
+// src/app/controllers/row.js:95
+
+--
+// src/app/controllers/row.js:103
+
+include::panels/bettermap.asciidoc[]
+// src/app/panels/bettermap/module.js:1
+
+include::panels/column.asciidoc[]
+// src/app/panels/column/module.js:1
+
+include::panels/histogram.asciidoc[]
+// src/app/panels/histogram/module.js:1
+
+include::panels/hits.asciidoc[]
+// src/app/panels/hits/module.js:1
+
+include::panels/map.asciidoc[]
+// src/app/panels/map/module.js:1
+
+include::panels/pie.asciidoc[]
+// src/app/panels/pie/module.js:1
+
+include::panels/sparklines.asciidoc[]
+// src/app/panels/sparklines/module.js:1
+
+include::panels/table.asciidoc[]
+// src/app/panels/table/module.js:1
+
+include::panels/terms.asciidoc[]
+// src/app/panels/terms/module.js:1
+
+include::panels/text.asciidoc[]
+// src/app/panels/text/module.js:1
+
+include::panels/trends.asciidoc[]
+// src/app/panels/trends/module.js:1
+

docs/kibana/panels/bettermap.asciidoc

@@ -0,0 +1,36 @@
+== Bettermap
+Status: *Experimental*
+
+Bettermap is called bettermap for lack of a better name. Bettermap uses geographic coordinates to
+create clusters of markers on map and shade them orange, yellow and green depending on the
+density of the cluster.
+
+To drill down, click on a cluster. The map will be zoomed and the cluster broken into smaller cluster.
+When it no longer makes visual sense to cluster, individual markers will be displayed. Hover over
+a marker to see the tooltip value/
+
+IMPORTANT: bettermap requires an internet connection to download its map panels.
+// src/app/panels/bettermap/module.js:5
+
+=== Parameters
+
+field:: The field that contains the coordinates, in geojson format. GeoJSON is
++[longitude,latitude]+ in an array. This is different from most implementations, which use
+latitude, longitude.
+// src/app/panels/bettermap/module.js:62
+
+size:: The number of documents to use when drawing the map
+// src/app/panels/bettermap/module.js:70
+
+spyable:: Should the `inspect` icon be shown?
+// src/app/panels/bettermap/module.js:74
+
+tooltip:: Which field to use for the tooltip when hovering over a marker
+// src/app/panels/bettermap/module.js:78
+
+==== Queries
+queries object:: This object describes the queries to use on this panel.
+queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+queries.ids::: In +selected+ mode, which query ids are selected.
+// src/app/panels/bettermap/module.js:82
+

docs/kibana/panels/column.asciidoc

@@ -0,0 +1,14 @@
+== Column
+Status: *Stable*
+
+A pseudo panel that lets you add other panels to be arranged in a column with defined heights.
+While the column panel is stable, it does have many limitations, including the inability to drag
+and drop panels within its borders. It may be removed in a future release.
+
+// src/app/panels/column/module.js:5
+
+=== Parameters
+
+panel:: An array of panel objects
+// src/app/panels/column/module.js:36
+

docs/kibana/panels/histogram.asciidoc

@@ -0,0 +1,129 @@
+== Histogram
+Status: *Stable*
+
+The histogram panel allow for the display of time charts. It includes several modes and tranformations
+to display event counts, mean, min, max and total of numeric fields, and derivatives of counter
+fields.
+
+// src/app/panels/histogram/module.js:5
+
+=== Parameters
+==== Axis options
+mode:: Value to use for the y-axis. For all modes other than count, +value_field+ must be
+defined. Possible values: count, mean, max, min, total.
+// src/app/panels/histogram/module.js:65
+
+time_field:: x-axis field. This must be defined as a date type in Elasticsearch.
+// src/app/panels/histogram/module.js:72
+
+value_field:: y-axis field if +mode+ is set to mean, max, min or total. Must be numeric.
+// src/app/panels/histogram/module.js:76
+
+x-axis:: Show the x-axis
+// src/app/panels/histogram/module.js:80
+
+y-axis:: Show the y-axis
+// src/app/panels/histogram/module.js:84
+
+scale:: Scale the y-axis by this factor
+// src/app/panels/histogram/module.js:88
+
+y_as_bytes:: Show the y-axis scale as bytes, automatically round to KB, MB, GB, etc.
+// src/app/panels/histogram/module.js:92
+
+==== Annotations
+annotate object:: A query can be specified, the results of which will be displayed as markers on
+the chart. For example, for noting code deploys.
+annotate.enable::: Should annotations, aka markers, be shown?
+annotate.query::: Lucene query_string syntax query to use for markers.
+annotate.size::: Max number of markers to show
+annotate.field::: Field from documents to show
+annotate.sort::: Sort array in format [field,order], For example [`@timestamp',`desc']
+// src/app/panels/histogram/module.js:115
+
+==== Interval options
+auto_int:: Automatically scale intervals?
+// src/app/panels/histogram/module.js:132
+
+resolution:: If auto_int is true, shoot for this many bars.
+// src/app/panels/histogram/module.js:137
+
+interval:: If auto_int is set to false, use this as the interval.
+// src/app/panels/histogram/module.js:141
+
+interval:: Array of possible intervals in the *View* selector. Example [`auto',`1s',`5m',`3h']
+// src/app/panels/histogram/module.js:145
+
+==== Drawing options
+lines:: Show line chart
+// src/app/panels/histogram/module.js:149
+
+fill:: Area fill factor for line charts, 1-10
+// src/app/panels/histogram/module.js:154
+
+linewidth:: Weight of lines in pixels
+// src/app/panels/histogram/module.js:158
+
+points:: Show points on chart
+// src/app/panels/histogram/module.js:162
+
+pointradius:: Size of points in pixels
+// src/app/panels/histogram/module.js:166
+
+bars:: Show bars on chart
+// src/app/panels/histogram/module.js:170
+
+stack:: Stack multiple series
+// src/app/panels/histogram/module.js:174
+
+spyable:: Show inspect icon
+// src/app/panels/histogram/module.js:178
+
+zoomlinks:: Show `Zoom Out' link
+// src/app/panels/histogram/module.js:182
+
+options:: Show quick view options section
+// src/app/panels/histogram/module.js:186
+
+legend:: Display the legond
+// src/app/panels/histogram/module.js:190
+
+show_query:: If no alias is set, should the query be displayed?
+// src/app/panels/histogram/module.js:194
+
+interactive:: Enable click-and-drag to zoom functionality
+// src/app/panels/histogram/module.js:198
+
+legend_counts:: Show counts in legend
+// src/app/panels/histogram/module.js:202
+
+==== Transformations
+timezone:: Correct for browser timezone?. Valid values: browser, utc
+// src/app/panels/histogram/module.js:206
+
+percentage:: Show the y-axis as a percentage of the axis total. Only makes sense for multiple
+queries
+// src/app/panels/histogram/module.js:211
+
+zerofill:: Improves the accuracy of line charts at a small performance cost.
+// src/app/panels/histogram/module.js:216
+
+derivative:: Show each point on the x-axis as the change from the previous point
+// src/app/panels/histogram/module.js:220
+
+tooltip object::
+tooltip.value_type::: Individual or cumulative controls how tooltips are display on stacked charts
+tooltip.query_as_alias::: If no alias is set, should the query be displayed?
+// src/app/panels/histogram/module.js:224
+
+grid object:: Min and max y-axis values
+grid.min::: Minimum y-axis value
+grid.max::: Maximum y-axis value
+// src/app/panels/histogram/module.js:96
+
+==== Queries
+queries object:: This object describes the queries to use on this panel.
+queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+queries.ids::: In +selected+ mode, which query ids are selected.
+// src/app/panels/histogram/module.js:105
+

docs/kibana/panels/hits.asciidoc

@@ -0,0 +1,37 @@
+== Hits
+Status: *Stable*
+
+The hits panel displays the number of hits for each of the queries on the dashboard in a
+configurable format specified by the `chart' property.
+
+// src/app/panels/hits/module.js:5
+
+=== Parameters
+
+arrangement:: The arrangement of the legend. horizontal or vertical
+// src/app/panels/hits/module.js:49
+
+chart:: bar, pie or none
+// src/app/panels/hits/module.js:55
+
+counter_pos:: The position of the legend, above or below
+// src/app/panels/hits/module.js:59
+
+donut:: If the chart is set to pie, setting donut to true will draw a hole in the midle of it
+// src/app/panels/hits/module.js:63
+
+tilt:: If the chart is set to pie, setting tilt to true will tilt it back into an oval
+// src/app/panels/hits/module.js:67
+
+labels:: If the chart is set to pie, setting labels to true will draw labels in the slices
+// src/app/panels/hits/module.js:71
+
+spyable:: Setting spyable to false disables the inspect icon.
+// src/app/panels/hits/module.js:75
+
+==== Queries
+queries object:: This object describes the queries to use on this panel.
+queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+queries.ids::: In +selected+ mode, which query ids are selected.
+// src/app/panels/hits/module.js:79
+

docs/kibana/panels/map.asciidoc

@@ -0,0 +1,32 @@
+== Map
+Status: *Stable*
+
+The map panel translates 2 letter country or state codes into shaded regions on a map. Currently
+available maps are world, usa and europe.
+
+// src/app/panels/map/module.js:5
+
+=== Parameters
+
+map:: Map to display. world, usa, europe
+// src/app/panels/map/module.js:48
+
+colors:: An array of colors to use to shade the map. If 2 colors are specified, shades
+between them will be used. For example [`#A0E2E2', `#265656']
+// src/app/panels/map/module.js:54
+
+size:: Max number of regions to shade
+// src/app/panels/map/module.js:59
+
+exclude:: exclude this array of regions. For example [`US',`BR',`IN']
+// src/app/panels/map/module.js:63
+
+spyable:: Setting spyable to false disables the inspect icon.
+// src/app/panels/map/module.js:67
+
+==== Queries
+queries object:: This object describes the queries to use on this panel.
+queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+queries.ids::: In +selected+ mode, which query ids are selected.
+// src/app/panels/map/module.js:71
+

docs/kibana/panels/pie.asciidoc

@@ -0,0 +1,50 @@
+== Pie
+Status: *Deprecated*
+
+The pie panel has been largely replaced by the +terms+ panel. It exists for backwards compatibility
+for now, but will be removed in a future release
+
+// src/app/panels/pie/module.js:5
+
+=== Parameters
+
+mode:: terms or goal. Terms mode finds the top N most popular terms, Goal mode display
+progress towards a fix goal in terms of documents matched
+// src/app/panels/pie/module.js:48
+
+size:: The max number of results to display in +terms+ mode.
+// src/app/panels/pie/module.js:55
+
+exclude:: Exclude these terms in terms mode
+// src/app/panels/pie/module.js:59
+
+donut:: Draw a hole in the middle of the pie, creating a tasty donut.
+// src/app/panels/pie/module.js:63
+
+tilt:: Tilt the pie back into an oval shape
+// src/app/panels/pie/module.js:67
+
+legend:: The location of the legend, above, below or none
+// src/app/panels/pie/module.js:71
+
+labels:: Set to false to disable drawing labels inside the pie slices
+// src/app/panels/pie/module.js:75
+
+spyable:: Set to false to disable the inspect function.
+// src/app/panels/pie/module.js:79
+
+==== Query
+
+query object:: This confusingly named object has properties to set the terms mode field,
+and the fixed goal for the goal mode
+query.field::: the field to facet on in terms mode
+query.goal::: the fixed goal for goal mode
+// src/app/panels/pie/module.js:83
+
+==== Queries
+
+queries object:: This object describes the queries to use on this panel.
+queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+queries.ids::: In +selected+ mode, which query ids are selected.
+// src/app/panels/pie/module.js:92
+

docs/kibana/panels/sparklines.asciidoc

@@ -0,0 +1,32 @@
+== Sparklines
+Status: *Experimental*
+
+The sparklines panel shows tiny time charts. The purpose of these is not to give an exact value,
+but rather to show the shape of the time series in a compact manner
+
+// src/app/panels/sparklines/module.js:5
+
+=== Parameters
+mode:: Value to use for the y-axis. For all modes other than count, +value_field+ must be
+defined. Possible values: count, mean, max, min, total.
+// src/app/panels/sparklines/module.js:56
+
+time_field:: x-axis field. This must be defined as a date type in Elasticsearch.
+// src/app/panels/sparklines/module.js:62
+
+value_field:: y-axis field if +mode+ is set to mean, max, min or total. Must be numeric.
+// src/app/panels/sparklines/module.js:66
+
+interval:: Sparkline intervals are computed automatically as long as there is a time filter
+present. In the absence of a time filter, use this interval.
+// src/app/panels/sparklines/module.js:70
+
+spyable:: Show inspect icon
+// src/app/panels/sparklines/module.js:75
+
+==== Queries
+queries object:: This object describes the queries to use on this panel.
+queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+queries.ids::: In +selected+ mode, which query ids are selected.
+// src/app/panels/sparklines/module.js:79
+

docs/kibana/panels/table.asciidoc

@@ -0,0 +1,63 @@
+== table
+Status: *Stable*
+
+The table panel contains a sortable, pagable view of documents that. It can be arranged into
+defined columns and offers several interactions, such as performing adhoc terms aggregations.
+
+// src/app/panels/table/module.js:5
+
+=== Parameters
+
+size:: The number of hits to show per page
+// src/app/panels/table/module.js:53
+
+pages:: The number of pages available
+// src/app/panels/table/module.js:59
+
+offset:: The current page
+// src/app/panels/table/module.js:63
+
+sort:: An array describing the sort order of the table. For example [`@timestamp',`desc']
+// src/app/panels/table/module.js:67
+
+overflow:: The css overflow property. `min-height' (expand) or `auto' (scroll)
+// src/app/panels/table/module.js:71
+
+fields:: the fields used a columns of the table, in an array.
+// src/app/panels/table/module.js:75
+
+highlight:: The fields on which to highlight, in an array
+// src/app/panels/table/module.js:79
+
+sortable:: Set sortable to false to disable sorting
+// src/app/panels/table/module.js:83
+
+header:: Set to false to hide the table column names
+// src/app/panels/table/module.js:87
+
+paging:: Set to false to hide the paging controls of the table
+// src/app/panels/table/module.js:91
+
+field_list:: Set to false to hide the list of fields. The user will be able to expand it,
+but it will be hidden by default
+// src/app/panels/table/module.js:95
+
+all_fields:: Set to true to show all fields in the mapping, not just the current fields in
+the table.
+// src/app/panels/table/module.js:100
+
+trimFactor:: The trim factor is the length at which to truncate fields takinging into
+consideration the number of columns in the table. For example, a trimFactor of 100, with 5
+columns in the table, would trim each column at 20 character. The entirety of the field is
+still available in the expanded view of the event.
+// src/app/panels/table/module.js:105
+
+spyable:: Set to false to disable the inspect icon
+// src/app/panels/table/module.js:112
+
+==== Queries
+queries object:: This object describes the queries to use on this panel.
+queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+queries.ids::: In +selected+ mode, which query ids are selected.
+// src/app/panels/table/module.js:116
+

docs/kibana/panels/terms.asciidoc

@@ -0,0 +1,56 @@
+== terms
+Status: *Stable*
+
+A table, bar chart or pie chart based on the results of an Elasticsearch terms facet.
+
+// src/app/panels/terms/module.js:5
+
+=== Parameters
+
+field:: The field on which to computer the facet
+// src/app/panels/terms/module.js:45
+
+exclude:: terms to exclude from the results
+// src/app/panels/terms/module.js:51
+
+missing:: Set to false to disable the display of a counter showing how much results are
+missing the field
+// src/app/panels/terms/module.js:55
+
+other:: Set to false to disable the display of a counter representing the aggregate of all
+values outside of the scope of your +size+ property
+// src/app/panels/terms/module.js:60
+
+size:: Show this many terms
+// src/app/panels/terms/module.js:65
+
+order:: count, term, reverse_count or reverse_term
+// src/app/panels/terms/module.js:69
+
+donut:: In pie chart mode, draw a hole in the middle of the pie to make a tasty donut.
+// src/app/panels/terms/module.js:74
+
+tilt:: In pie chart mode, tilt the chart back to appear as more of an oval shape
+// src/app/panels/terms/module.js:78
+
+lables:: In pie chart mode, draw labels in the pie slices
+// src/app/panels/terms/module.js:82
+
+arrangement:: In bar or pie mode, arrangement of the legend. horizontal or vertical
+// src/app/panels/terms/module.js:86
+
+chart:: table, bar or pie
+// src/app/panels/terms/module.js:90
+
+counter_pos:: The location of the legend in respect to the chart, above or below.
+// src/app/panels/terms/module.js:94
+
+spyable:: Set spyable to false to disable the inspect button
+// src/app/panels/terms/module.js:98
+
+==== Queries
+queries object:: This object describes the queries to use on this panel.
+queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+queries.ids::: In +selected+ mode, which query ids are selected.
+// src/app/panels/terms/module.js:102
+

docs/kibana/panels/text.asciidoc

@@ -0,0 +1,16 @@
+== text
+Status: *Stable*
+
+The text panel is used for displaying static text formated as markdown, sanitized html or as plain
+text.
+
+// src/app/panels/text/module.js:5
+
+=== Parameters
+
+mode:: `html', `markdown' or `text'
+// src/app/panels/text/module.js:33
+
+content:: The content of your panel, written in the mark up specified in +mode+
+// src/app/panels/text/module.js:39
+

docs/kibana/panels/trends.asciidoc

@@ -0,0 +1,27 @@
+== trends
+Status: *Beta*
+
+A stock-ticker style representation of how queries are moving over time. For example, if the
+time is 1:10pm, your time picker was set to "Last 10m", and the "Time Ago" parameter was set to
+"1h", the panel would show how much the query results have changed since 12:00-12:10pm
+
+// src/app/panels/trends/module.js:5
+
+=== Parameters
+
+ago:: A date math formatted string describing the relative time period to compare the
+queries to.
+// src/app/panels/trends/module.js:49
+
+arrangement:: `horizontal' or `vertical'
+// src/app/panels/trends/module.js:56
+
+spyable:: Set to false to disable the inspect icon
+// src/app/panels/trends/module.js:60
+
+==== Queries
+queries object:: This object describes the queries to use on this panel.
+queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+queries.ids::: In +selected+ mode, which query ids are selected.
+// src/app/panels/trends/module.js:64
+

src/app/controllers/dash.js

@@ -1,3 +1,22 @@
+/** @scratch /index/0
+ * = Kibana
+ *
+ * // Why can't I have a preamble here?
+ *
+ * == Introduction
+ *
+ * Kibana is an open source (Apache Licensed), browser based analytics and search dashboard for
+ * ElasticSearch. Kibana is a snap to setup and start using. Written entirely in HTML and Javascript
+ * it requires only a plain webserver, Kibana requires no fancy server side components.
+ * Kibana strives to be easy to get started with, while also being flexible and powerful, just like
+ * Elasticsearch.
+ *
+ * include::configuration/config.js.asciidoc[]
+ *
+ * include::panels.asciidoc[]
+ *
+ */
+
 define([
   'angular',
   'config',

src/app/controllers/row.js

@@ -58,6 +58,25 @@ function (angular, app, _) {
         $scope.row.panels.push(panel);
       };
 
+      /** @scratch /panels/0
+       * [[panels]]
+       * = Panels
+       *
+       * [partintro]
+       * --
+       * *Kibana* dashboards are made up of blocks called +panels+. Panels are organized into rows
+       * and can serve many purposes, though most are designed to provide the results of a query or
+       * multiple queries as a visualization. Other panels may show collections of documents or
+       * allow you to insert instructions for your users.
+       *
+       * Panels can be configured easily via the Kibana web interface. For more advanced usage, such
+       * as templated or scripted dashboards, documentation of panel properties is available in this
+       * section. You may find settings here which are not exposed via the web interface.
+       *
+       * Each panel type has its own properties, hover there are several that are shared.
+       *
+      */
+
       $scope.reset_panel = function(type) {
         var
           defaultSpan = 4,
@@ -65,12 +84,26 @@ function (angular, app, _) {
 
         $scope.panel = {
           error   : false,
+          /** @scratch /panels/1
+           * span:: A number, 1-12, that describes the width of the panel.
+           */
           span    : _as < defaultSpan && _as > 0 ? _as : defaultSpan,
+          /** @scratch /panels/1
+           * editable:: Enable or disable the edit button the the panel
+           */
           editable: true,
+          /** @scratch /panels/1
+           * type:: The type of panel this object contains. Each panel type will require additional
+           * properties. See the panel types list to the right.
+           */
           type    : type
         };
       };
 
+      /** @scratch /panels/2
+       * --
+       */
+
       $scope.init();
 
     }

src/app/panels/bettermap/module.js

@@ -1,13 +1,21 @@
-/*
+/** @scratch /panels/5
+ * include::panels/bettermap.asciidoc[]
+ */
 
-  ## Better maps
+/** @scratch /panels/bettermap/0
-
+ * == Bettermap
-  ### Parameters
+ * Status: *Experimental*
-  * size :: How many results to show, more results = slower
+ *
-  * field :: field containing a 2 element array in the format [lon,lat]
+ * Bettermap is called bettermap for lack of a better name. Bettermap uses geographic coordinates to
-  * tooltip :: field to extract the tool tip value from
+ * create clusters of markers on map and shade them orange, yellow and green depending on the
-  * spyable :: Show the 'eye' icon that reveals the last ES query
+ * density of the cluster.
-*/
+ *
+ * To drill down, click on a cluster. The map will be zoomed and the cluster broken into smaller cluster.
+ * When it no longer makes visual sense to cluster, individual markers will be displayed. Hover over
+ * a marker to see the tooltip value/
+ *
+ * IMPORTANT: bettermap requires an internet connection to download its map panels.
+ */
 define([
   'angular',
   'app',
@@ -51,21 +59,43 @@ function (angular, app, _, L, localRequire) {
 
     // Set and populate defaults
     var _d = {
+      /** @scratch /panels/bettermap/3
+       * === Parameters
+       *
+       * field:: The field that contains the coordinates, in geojson format. GeoJSON is
+       * +[longitude,latitude]+ in an array. This is different from most implementations, which use
+       * latitude, longitude.
+       */
+      field   : null,
+      /** @scratch /panels/bettermap/5
+       * size:: The number of documents to use when drawing the map
+       */
+      size    : 1000,
+      /** @scratch /panels/bettermap/5
+       * spyable:: Should the `inspect` icon be shown?
+       */
+      spyable : true,
+      /** @scratch /panels/bettermap/5
+       * tooltip:: Which field to use for the tooltip when hovering over a marker
+       */
+      tooltip : "_id",
+      /** @scratch /panels/bettermap/5
+       * ==== Queries
+       * queries object:: This object describes the queries to use on this panel.
+       * queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+       * queries.ids::: In +selected+ mode, which query ids are selected.
+       */
       queries     : {
         mode        : 'all',
         ids         : []
       },
-      size    : 1000,
-      spyable : true,
-      tooltip : "_id",
-      field   : null
     };
 
     _.defaults($scope.panel,_d);
-    $scope.requireContext = localRequire;
 
     // inorder to use relative paths in require calls, require needs a context to run. Without
     // setting this property the paths would be relative to the app not this context/file.
+    $scope.requireContext = localRequire;
 
     $scope.init = function() {
       $scope.$on('refresh',function(){
@@ -204,6 +234,7 @@ function (angular, app, _, L, localRequire) {
                 zoom: 10
               });
 
+              // This could be made configurable?
               L.tileLayer('http://{s}.tile.cloudmade.com/57cbb6ca8cac418dbb1a402586df4528/22677/256/{z}/{x}/{y}.png', {
                 maxZoom: 18,
                 minZoom: 2

src/app/panels/column/module.js

@@ -1,11 +1,16 @@
-/*
+/** @scratch /panels/5
+ * include::panels/column.asciidoc[]
+ */
 
-  ## Column
+/** @scratch /panels/column/0
-
+ * == Column
-  ### Parameters
+ * Status: *Stable*
-  * panels :: an array of panel objects. All of their spans should be set to 12
+ *
-
+ * A pseudo panel that lets you add other panels to be arranged in a column with defined heights.
-*/
+ * While the column panel is stable, it does have many limitations, including the inability to drag
+ * and drop panels within its borders. It may be removed in a future release.
+ *
+ */
 define([
   'angular',
   'app',
@@ -28,6 +33,11 @@ function (angular, app, _, config) {
 
     // Set and populate defaults
     var _d = {
+      /** @scratch /panels/column/3
+       * === Parameters
+       *
+       * panel:: An array of panel objects
+       */
       panels : []
     };
     _.defaults($scope.panel,_d);

src/app/panels/histogram/module.js

@@ -1,32 +1,16 @@
-/*
+/** @scratch /panels/5
+ * include::panels/histogram.asciidoc[]
+ */
 
-  ## Histogram
+/** @scratch /panels/histogram/0
-
+ * == Histogram
-  ### Parameters
+ * Status: *Stable*
-  * auto_int :: Auto calculate data point interval?
+ *
-  * resolution ::  If auto_int is enables, shoot for this many data points, rounding to
+ * The histogram panel allow for the display of time charts. It includes several modes and tranformations
-                    sane intervals
+ * to display event counts, mean, min, max and total of numeric fields, and derivatives of counter
-  * interval :: Datapoint interval in elasticsearch date math format (eg 1d, 1w, 1y, 5y)
+ * fields.
-  * fill :: Only applies to line charts. Level of area shading from 0-10
+ *
-  * linewidth ::  Only applies to line charts. How thick the line should be in pixels
+ */
-                  While the editor only exposes 0-10, this can be any numeric value.
-                  Set to 0 and you'll get something like a scatter plot
-  * timezone :: This isn't totally functional yet. Currently only supports browser and utc.
-                browser will adjust the x-axis labels to match the timezone of the user's
-                browser
-  * spyable ::  Dislay the 'eye' icon that show the last elasticsearch query
-  * zoomlinks :: Show the zoom links?
-  * bars :: Show bars in the chart
-  * stack :: Stack multiple queries. This generally a crappy way to represent things.
-             You probably should just use a line chart without stacking
-  * points :: Should circles at the data points on the chart
-  * lines :: Line chart? Sweet.
-  * legend :: Show the legend?
-  * x-axis :: Show x-axis labels and grid lines
-  * y-axis :: Show y-axis labels and grid lines
-  * interactive :: Allow drag to select time range
-
-*/
 define([
   'angular',
   'app',
@@ -78,12 +62,66 @@ function (angular, app, $, _, kbn, moment, timeSeries) {
 
     // Set and populate defaults
     var _d = {
+      /** @scratch /panels/histogram/3
+       * === Parameters
+       * ==== Axis options
+       * mode:: Value to use for the y-axis. For all modes other than count, +value_field+ must be
+       * defined. Possible values: count, mean, max, min, total.
+       */
       mode          : 'count',
+      /** @scratch /panels/histogram/3
+       * time_field:: x-axis field. This must be defined as a date type in Elasticsearch.
+       */
       time_field    : '@timestamp',
-      queries       : {
+      /** @scratch /panels/histogram/3
-        mode          : 'all',
+       * value_field:: y-axis field if +mode+ is set to mean, max, min or total. Must be numeric.
-        ids           : []
+       */
+      value_field   : null,
+      /** @scratch /panels/histogram/3
+       * x-axis:: Show the x-axis
+       */
+      'x-axis'      : true,
+      /** @scratch /panels/histogram/3
+       * y-axis:: Show the y-axis
+       */
+      'y-axis'      : true,
+      /** @scratch /panels/histogram/3
+       * scale:: Scale the y-axis by this factor
+       */
+      scale         : 1,
+      /** @scratch /panels/histogram/3
+       * y_as_bytes:: Show the y-axis scale as bytes, automatically round to KB, MB, GB, etc.
+       */
+      y_as_bytes    : false,
+      /** @scratch /panels/histogram/5
+       * grid object:: Min and max y-axis values
+       * grid.min::: Minimum y-axis value
+       * grid.max::: Maximum y-axis value
+       */
+      grid          : {
+        max: null,
+        min: 0
       },
+      /** @scratch /panels/histogram/5
+       * ==== Queries
+       * queries object:: This object describes the queries to use on this panel.
+       * queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+       * queries.ids::: In +selected+ mode, which query ids are selected.
+       */
+      queries     : {
+        mode        : 'all',
+        ids         : []
+      },
+      /** @scratch /panels/histogram/3
+       * ==== Annotations
+       * annotate object:: A query can be specified, the results of which will be displayed as markers on
+       * the chart. For example, for noting code deploys.
+       * annotate.enable::: Should annotations, aka markers, be shown?
+       * annotate.query::: Lucene query_string syntax query to use for markers.
+       * annotate.size::: Max number of markers to show
+       * annotate.field::: Field from documents to show
+       * annotate.sort::: Sort array in format [field,order], For example [`@timestamp',`desc']
+       */
       annotate      : {
         enable      : false,
         query       : "*",
@@ -91,40 +129,106 @@ function (angular, app, $, _, kbn, moment, timeSeries) {
         field       : '_type',
         sort        : ['_score','desc']
       },
-      value_field   : null,
+      /** @scratch /panels/histogram/3
+       * ==== Interval options
+       * auto_int:: Automatically scale intervals?
+       */
       auto_int      : true,
+      /** @scratch /panels/histogram/3
+       * resolution:: If auto_int is true, shoot for this many bars.
+       */
       resolution    : 100,
+      /** @scratch /panels/histogram/3
+       * interval:: If auto_int is set to false, use this as the interval.
+       */
       interval      : '5m',
+      /** @scratch /panels/histogram/3
+       * interval:: Array of possible intervals in the *View* selector. Example [`auto',`1s',`5m',`3h']
+       */
       intervals     : ['auto','1s','1m','5m','10m','30m','1h','3h','12h','1d','1w','1y'],
-      fill          : 0,
+      /** @scratch /panels/histogram/3
-      linewidth     : 3,
+       * ==== Drawing options
-      pointradius   : 5,
+       * lines:: Show line chart
-      timezone      : 'browser', // browser, utc or a standard timezone
+       */
-      spyable       : true,
-      zoomlinks     : true,
-      bars          : true,
-      stack         : true,
-      points        : false,
       lines         : false,
-      legend        : true,
+      /** @scratch /panels/histogram/3
-      show_query    : true,
+       * fill:: Area fill factor for line charts, 1-10
-      legend_counts : true,
+       */
-      'x-axis'      : true,
+      fill          : 0,
-      'y-axis'      : true,
+      /** @scratch /panels/histogram/3
-      percentage    : false,
+       * linewidth:: Weight of lines in pixels
-      zerofill      : true,
+       */
-      interactive   : true,
+      linewidth     : 3,
+      /** @scratch /panels/histogram/3
+       * points:: Show points on chart
+       */
+      points        : false,
+      /** @scratch /panels/histogram/3
+       * pointradius:: Size of points in pixels
+       */
+      pointradius   : 5,
+      /** @scratch /panels/histogram/3
+       * bars:: Show bars on chart
+       */
+      bars          : true,
+      /** @scratch /panels/histogram/3
+       * stack:: Stack multiple series
+       */
+      stack         : true,
+      /** @scratch /panels/histogram/3
+       * spyable:: Show inspect icon
+       */
+      spyable       : true,
+      /** @scratch /panels/histogram/3
+       * zoomlinks:: Show `Zoom Out' link
+       */
+      zoomlinks     : true,
+      /** @scratch /panels/histogram/3
+       * options:: Show quick view options section
+       */
       options       : true,
+      /** @scratch /panels/histogram/3
+       * legend:: Display the legond
+       */
+      legend        : true,
+      /** @scratch /panels/histogram/3
+       * show_query:: If no alias is set, should the query be displayed?
+       */
+      show_query    : true,
+      /** @scratch /panels/histogram/3
+       * interactive:: Enable click-and-drag to zoom functionality
+       */
+      interactive   : true,
+      /** @scratch /panels/histogram/3
+       * legend_counts:: Show counts in legend
+       */
+      legend_counts : true,
+      /** @scratch /panels/histogram/3
+       * ==== Transformations
+       * timezone:: Correct for browser timezone?. Valid values: browser, utc
+       */
+      timezone      : 'browser', // browser or utc
+      /** @scratch /panels/histogram/3
+       * percentage:: Show the y-axis as a percentage of the axis total. Only makes sense for multiple
+       * queries
+       */
+      percentage    : false,
+      /** @scratch /panels/histogram/3
+       * zerofill:: Improves the accuracy of line charts at a small performance cost.
+       */
+      zerofill      : true,
+      /** @scratch /panels/histogram/3
+       * derivative:: Show each point on the x-axis as the change from the previous point
+       */
       derivative    : false,
-      scale         : 1,
+      /** @scratch /panels/histogram/3
-      y_as_bytes    : false,
+       * tooltip object::
+       * tooltip.value_type::: Individual or cumulative controls how tooltips are display on stacked charts
+       * tooltip.query_as_alias::: If no alias is set, should the query be displayed?
+       */
       tooltip       : {
         value_type: 'cumulative',
         query_as_alias: true
-      },
-      grid          : {
-        max: null,
-        min: 0
       }
     };
 

src/app/panels/hits/module.js

@@ -1,16 +1,15 @@
-/*
+/** @scratch /panels/5
+ * include::panels/hits.asciidoc[]
+ */
 
-  ## Hits
+/** @scratch /panels/hits/0
-
+ * == Hits
-  ### Parameters
+ * Status: *Stable*
-  * style :: A hash of css styles
+ *
-  * arrangement :: How should I arrange the query results? 'horizontal' or 'vertical'
+ * The hits panel displays the number of hits for each of the queries on the dashboard in a
-  * chart :: Show a chart? 'none', 'bar', 'pie'
+ * configurable format specified by the `chart' property.
-  * donut :: Only applies to 'pie' charts. Punches a hole in the chart for some reason
+ *
-  * tilt :: Only 'pie' charts. Janky 3D effect. Looks terrible 90% of the time.
+ */
-  * lables :: Only 'pie' charts. Labels on the pie?
-
-*/
 define([
   'angular',
   'app',
@@ -46,18 +45,47 @@ define([
 
     // Set and populate defaults
     var _d = {
+      style   : { "font-size": '10pt'},
+      /** @scratch /panels/hits/3
+       * === Parameters
+       *
+       * arrangement:: The arrangement of the legend. horizontal or vertical
+       */
+      arrangement : 'horizontal',
+      /** @scratch /panels/hits/3
+       * chart:: bar, pie or none
+       */
+      chart       : 'bar',
+      /** @scratch /panels/hits/3
+       * counter_pos:: The position of the legend, above or below
+       */
+      counter_pos : 'above',
+      /** @scratch /panels/hits/3
+       * donut:: If the chart is set to pie, setting donut to true will draw a hole in the midle of it
+       */
+      donut   : false,
+      /** @scratch /panels/hits/3
+       * tilt:: If the chart is set to pie, setting tilt to true will tilt it back into an oval
+       */
+      tilt    : false,
+      /** @scratch /panels/hits/3
+       * labels:: If the chart is set to pie, setting labels to true will draw labels in the slices
+       */
+      labels  : true,
+      /** @scratch /panels/hits/3
+       * spyable:: Setting spyable to false disables the inspect icon.
+       */
+      spyable : true,
+      /** @scratch /panels/hits/5
+       * ==== Queries
+       * queries object:: This object describes the queries to use on this panel.
+       * queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+       * queries.ids::: In +selected+ mode, which query ids are selected.
+       */
       queries     : {
         mode        : 'all',
         ids         : []
       },
-      style   : { "font-size": '10pt'},
-      arrangement : 'horizontal',
-      chart       : 'bar',
-      counter_pos : 'above',
-      donut   : false,
-      tilt    : false,
-      labels  : true,
-      spyable : true
     };
     _.defaults($scope.panel,_d);
 

src/app/panels/map/module.js

@@ -1,19 +1,15 @@
-/*
+/** @scratch /panels/5
-
+ * include::panels/map.asciidoc[]
-  ## Map
+ */
-
-  ### Parameters
-  * map :: 'world', 'us' or 'europe'
-  * colors :: an array of colors to use for the regions of the map. If this is a 2
-              element array, jquerymap will generate shades between these colors
-  * size :: How big to make the facet. Higher = more countries
-  * exclude :: Exlude the array of counties
-  * spyable :: Show the 'eye' icon that reveals the last ES query
-  * index_limit :: This does nothing yet. Eventually will limit the query to the first
-                   N indices
-
-*/
 
+/** @scratch /panels/map/0
+ * == Map
+ * Status: *Stable*
+ *
+ * The map panel translates 2 letter country or state codes into shaded regions on a map. Currently
+ * available maps are world, usa and europe.
+ *
+ */
 define([
   'angular',
   'app',
@@ -49,16 +45,39 @@ function (angular, app, _, $) {
 
     // Set and populate defaults
     var _d = {
+      /** @scratch /panels/map/3
+       * === Parameters
+       *
+       * map:: Map to display. world, usa, europe
+       */
+      map     : "world",
+      /** @scratch /panels/map/3
+       * colors:: An array of colors to use to shade the map. If 2 colors are specified, shades
+       * between them will be used. For example [`#A0E2E2', `#265656']
+       */
+      colors  : ['#A0E2E2', '#265656'],
+      /** @scratch /panels/map/3
+       * size:: Max number of regions to shade
+       */
+      size    : 100,
+      /** @scratch /panels/map/3
+       * exclude:: exclude this array of regions. For example [`US',`BR',`IN']
+       */
+      exclude : [],
+      /** @scratch /panels/map/3
+       * spyable:: Setting spyable to false disables the inspect icon.
+       */
+      spyable : true,
+      /** @scratch /panels/map/5
+       * ==== Queries
+       * queries object:: This object describes the queries to use on this panel.
+       * queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+       * queries.ids::: In +selected+ mode, which query ids are selected.
+       */
       queries     : {
         mode        : 'all',
         ids         : []
-      },
+      }
-      map     : "world",
-      colors  : ['#A0E2E2', '#265656'],
-      size    : 100,
-      exclude : [],
-      spyable : true,
-      index_limit : 0
     };
     _.defaults($scope.panel,_d);
 

src/app/panels/pie/module.js

@@ -1,21 +1,15 @@
-/*
+/** @scratch /panels/5
+ * include::panels/pie.asciidoc[]
+ */
 
-  ## Pie
+/** @scratch /panels/pie/0
-
+ * == Pie
-  ### Parameters
+ * Status: *Deprecated*
-  * query :: An object with 2 possible parameters depends on the mode:
+ *
-  ** field: Fields to run a terms facet on. Only does anything in terms mode
+ * The pie panel has been largely replaced by the +terms+ panel. It exists for backwards compatibility
-  ** goal: How many to shoot for, only does anything in goal mode
+ * for now, but will be removed in a future release
-  * exclude :: In terms mode, ignore these terms
+ *
-  * donut :: Drill a big hole in the pie
+ */
-  * tilt :: A janky 3D representation of the pie. Looks terrible 90% of the time.
-  * legend :: Show the legend?
-  * labels :: Label the slices of the pie?
-  * mode :: 'terms' or 'goal'
-  * default_field ::  LOL wat? A dumb fail over field if for some reason the query object
-                      doesn't have a field
-  * spyable :: Show the 'eye' icon that displays the last ES query for this panel
-*/
 define([
   'angular',
   'app',
@@ -51,20 +45,63 @@ define([
 
     // Set and populate defaults
     var _d = {
+      /** @scratch /panels/pie/3
+       * === Parameters
+       *
+       * mode:: terms or goal. Terms mode finds the top N most popular terms, Goal mode display
+       * progress towards a fix goal in terms of documents matched
+       */
+      mode    : "terms",
+      /** @scratch /panels/pie/3
+       * size:: The max number of results to display in +terms+ mode.
+       */
+      size    : 10,
+      /** @scratch /panels/pie/3
+       * exclude:: Exclude these terms in terms mode
+       */
+      exclude : [],
+      /** @scratch /panels/pie/3
+       * donut:: Draw a hole in the middle of the pie, creating a tasty donut.
+       */
+      donut   : false,
+      /** @scratch /panels/pie/3
+       * tilt:: Tilt the pie back into an oval shape
+       */
+      tilt    : false,
+      /** @scratch /panels/pie/3
+       * legend:: The location of the legend, above, below or none
+       */
+      legend  : "above",
+      /** @scratch /panels/pie/3
+       * labels:: Set to false to disable drawing labels inside the pie slices
+       */
+      labels  : true,
+      /** @scratch /panels/pie/3
+       * spyable:: Set to false to disable the inspect function.
+       */
+      spyable : true,
+      /** @scratch /panels/pie/3
+       * ==== Query
+       *
+       * query object:: This confusingly named object has properties to set the terms mode field,
+       * and the fixed goal for the goal mode
+       * query.field::: the field to facet on in terms mode
+       * query.goal::: the fixed goal for goal mode
+       */
       query   : { field:"_type", goal: 100},
+      /** @scratch /panels/pie/5
+       * ==== Queries
+       *
+       * queries object:: This object describes the queries to use on this panel.
+       * queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+       * queries.ids::: In +selected+ mode, which query ids are selected.
+       */
       queries     : {
         mode        : 'all',
         ids         : []
       },
-      size    : 10,
+      default_field : '_type',
-      exclude : [],
+
-      donut   : false,
-      tilt    : false,
-      legend  : "above",
-      labels  : true,
-      mode    : "terms",
-      default_field : 'DEFAULT',
-      spyable : true,
     };
     _.defaults($scope.panel,_d);
 

src/app/panels/sparklines/module.js

@@ -1,32 +1,15 @@
-/*
+/** @scratch /panels/5
+ * include::panels/sparklines.asciidoc[]
+ */
 
-  ## Histogram
+/** @scratch /panels/sparklines/0
-
+ * == Sparklines
-  ### Parameters
+ * Status: *Experimental*
-  * auto_int :: Auto calculate data point interval?
+ *
-  * resolution ::  If auto_int is enables, shoot for this many data points, rounding to
+ * The sparklines panel shows tiny time charts. The purpose of these is not to give an exact value,
-                    sane intervals
+ * but rather to show the shape of the time series in a compact manner
-  * interval :: Datapoint interval in elasticsearch date math format (eg 1d, 1w, 1y, 5y)
+ *
-  * fill :: Only applies to line charts. Level of area shading from 0-10
+ */
-  * linewidth ::  Only applies to line charts. How thick the line should be in pixels
-                  While the editor only exposes 0-10, this can be any numeric value.
-                  Set to 0 and you'll get something like a scatter plot
-  * timezone :: This isn't totally functional yet. Currently only supports browser and utc.
-                browser will adjust the x-axis labels to match the timezone of the user's
-                browser
-  * spyable ::  Dislay the 'eye' icon that show the last elasticsearch query
-  * zoomlinks :: Show the zoom links?
-  * bars :: Show bars in the chart
-  * stack :: Stack multiple queries. This generally a crappy way to represent things.
-             You probably should just use a line chart without stacking
-  * points :: Should circles at the data points on the chart
-  * lines :: Line chart? Sweet.
-  * legend :: Show the legend?
-  * x-axis :: Show x-axis labels and grid lines
-  * y-axis :: Show y-axis labels and grid lines
-  * interactive :: Allow drag to select time range
-
-*/
 define([
   'angular',
   'app',
@@ -70,15 +53,39 @@ function (angular, app, $, _, kbn, moment, timeSeries) {
 
     // Set and populate defaults
     var _d = {
+      /** @scratch /panels/sparklines/3
+       * === Parameters
+       * mode:: Value to use for the y-axis. For all modes other than count, +value_field+ must be
+       * defined. Possible values: count, mean, max, min, total.
+       */
       mode          : 'count',
+      /** @scratch /panels/sparklines/3
+       * time_field:: x-axis field. This must be defined as a date type in Elasticsearch.
+       */
       time_field    : '@timestamp',
-      queries       : {
+      /** @scratch /panels/sparklines/3
-        mode          : 'all',
+       * value_field:: y-axis field if +mode+ is set to mean, max, min or total. Must be numeric.
-        ids           : []
+       */
-      },
       value_field   : null,
+      /** @scratch /panels/sparklines/3
+       * interval:: Sparkline intervals are computed automatically as long as there is a time filter
+       * present. In the absence of a time filter, use this interval.
+       */
       interval      : '5m',
-      spyable       : true
+      /** @scratch /panels/sparklines/3
+       * spyable:: Show inspect icon
+       */
+      spyable       : true,
+      /** @scratch /panels/sparklines/5
+       * ==== Queries
+       * queries object:: This object describes the queries to use on this panel.
+       * queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+       * queries.ids::: In +selected+ mode, which query ids are selected.
+       */
+      queries     : {
+        mode        : 'all',
+        ids         : []
+      },
     };
 
     _.defaults($scope.panel,_d);

src/app/panels/table/module.js

@@ -1,31 +1,21 @@
-/*
+/** @scratch /panels/5
+ * include::panels/table.asciidoc[]
+ */
 
-  ## Table
+/** @scratch /panels/table/0
-
+ * == table
-  ### Parameters
+ * Status: *Stable*
-  * size :: Number of events per page to show
+ *
-  * pages :: Number of pages to show. size * pages = number of cached events.
+ * The table panel contains a sortable, pagable view of documents that. It can be arranged into
-             Bigger = more memory usage byh the browser
+ * defined columns and offers several interactions, such as performing adhoc terms aggregations.
-  * offset :: Position from which to start in the array of hits
+ *
-  * sort :: An array with 2 elements. sort[0]: field, sort[1]: direction ('asc' or 'desc')
+ */
-  * style :: hash of css properties
-  * fields :: columns to show in table
-  * overflow :: 'height' or 'min-height' controls wether the row will expand (min-height) to
-                to fit the table, or if the table will scroll to fit the row (height)
-  * trimFactor :: If line is > this many characters, divided by the number of columns, trim it.
-  * sortable :: Allow sorting?
-  * spyable :: Show the 'eye' icon that reveals the last ES query for this panel
-
-*/
 define([
   'angular',
   'app',
   'underscore',
   'kbn',
   'moment',
-
-  // 'text!./pagination.html',
-  // 'text!partials/querySelect.html'
 ],
 function (angular, app, _, kbn, moment) {
   'use strict';
@@ -60,27 +50,81 @@ function (angular, app, _, kbn, moment) {
 
     // Set and populate defaults
     var _d = {
+      /** @scratch /panels/table/5
+       * === Parameters
+       *
+       * size:: The number of hits to show per page
+       */
+      size    : 100, // Per page
+      /** @scratch /panels/table/5
+       * pages:: The number of pages available
+       */
+      pages   : 5,   // Pages available
+      /** @scratch /panels/table/5
+       * offset:: The current page
+       */
+      offset  : 0,
+      /** @scratch /panels/table/5
+       * sort:: An array describing the sort order of the table. For example [`@timestamp',`desc']
+       */
+      sort    : ['_score','desc'],
+      /** @scratch /panels/table/5
+       * overflow:: The css overflow property. `min-height' (expand) or `auto' (scroll)
+       */
+      overflow: 'min-height',
+      /** @scratch /panels/table/5
+       * fields:: the fields used a columns of the table, in an array.
+       */
+      fields  : [],
+      /** @scratch /panels/table/5
+       * highlight:: The fields on which to highlight, in an array
+       */
+      highlight : [],
+      /** @scratch /panels/table/5
+       * sortable:: Set sortable to false to disable sorting
+       */
+      sortable: true,
+      /** @scratch /panels/table/5
+       * header:: Set to false to hide the table column names
+       */
+      header  : true,
+      /** @scratch /panels/table/5
+       * paging:: Set to false to hide the paging controls of the table
+       */
+      paging  : true,
+      /** @scratch /panels/table/5
+       * field_list:: Set to false to hide the list of fields. The user will be able to expand it,
+       * but it will be hidden by default
+       */
+      field_list: true,
+      /** @scratch /panels/table/5
+       * all_fields:: Set to true to show all fields in the mapping, not just the current fields in
+       * the table.
+       */
+      all_fields: false,
+      /** @scratch /panels/table/5
+       * trimFactor:: The trim factor is the length at which to truncate fields takinging into
+       * consideration the number of columns in the table. For example, a trimFactor of 100, with 5
+       * columns in the table, would trim each column at 20 character. The entirety of the field is
+       * still available in the expanded view of the event.
+       */
+      trimFactor: 300,
+      /** @scratch /panels/table/5
+       * spyable:: Set to false to disable the inspect icon
+       */
+      spyable : true,
+      /** @scratch /panels/table/5
+       * ==== Queries
+       * queries object:: This object describes the queries to use on this panel.
+       * queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+       * queries.ids::: In +selected+ mode, which query ids are selected.
+       */
       queries     : {
         mode        : 'all',
         ids         : []
       },
-      size    : 100, // Per page
-      pages   : 5,   // Pages available
-      offset  : 0,
-      sort    : ['_score','desc'],
-      group   : "default",
       style   : {'font-size': '9pt'},
-      overflow: 'min-height',
-      fields  : [],
-      highlight : [],
-      sortable: true,
-      header  : true,
-      paging  : true,
-      field_list: true,
-      all_fields: false,
-      trimFactor: 300,
       normTimes : true,
-      spyable : true
     };
     _.defaults($scope.panel,_d);
 

src/app/panels/terms/module.js

@@ -1,15 +1,14 @@
-/*
+/** @scratch /panels/5
-  ## Terms
+ * include::panels/terms.asciidoc[]
+ */
 
-  ### Parameters
+/** @scratch /panels/terms/0
-  * style :: A hash of css styles
+ * == terms
-  * size :: top N
+ * Status: *Stable*
-  * arrangement :: How should I arrange the query results? 'horizontal' or 'vertical'
+ *
-  * chart :: Show a chart? 'none', 'bar', 'pie'
+ * A table, bar chart or pie chart based on the results of an Elasticsearch terms facet.
-  * donut :: Only applies to 'pie' charts. Punches a hole in the chart for some reason
+ *
-  * tilt :: Only 'pie' charts. Janky 3D effect. Looks terrible 90% of the time.
+ */
-  * lables :: Only 'pie' charts. Labels on the pie?
-*/
 define([
   'angular',
   'app',
@@ -43,24 +42,73 @@ function (angular, app, _, $, kbn) {
 
     // Set and populate defaults
     var _d = {
+      /** @scratch /panels/terms/5
+       * === Parameters
+       *
+       * field:: The field on which to computer the facet
+       */
+      field   : '_type',
+      /** @scratch /panels/terms/5
+       * exclude:: terms to exclude from the results
+       */
+      exclude : [],
+      /** @scratch /panels/terms/5
+       * missing:: Set to false to disable the display of a counter showing how much results are
+       * missing the field
+       */
+      missing : true,
+      /** @scratch /panels/terms/5
+       * other:: Set to false to disable the display of a counter representing the aggregate of all
+       * values outside of the scope of your +size+ property
+       */
+      other   : true,
+      /** @scratch /panels/terms/5
+       * size:: Show this many terms
+       */
+      size    : 10,
+      /** @scratch /panels/terms/5
+       * order:: count, term, reverse_count or reverse_term
+       */
+      order   : 'count',
+      style   : { "font-size": '10pt'},
+      /** @scratch /panels/terms/5
+       * donut:: In pie chart mode, draw a hole in the middle of the pie to make a tasty donut.
+       */
+      donut   : false,
+      /** @scratch /panels/terms/5
+       * tilt:: In pie chart mode, tilt the chart back to appear as more of an oval shape
+       */
+      tilt    : false,
+      /** @scratch /panels/terms/5
+       * lables:: In pie chart mode, draw labels in the pie slices
+       */
+      labels  : true,
+      /** @scratch /panels/terms/5
+       * arrangement:: In bar or pie mode, arrangement of the legend. horizontal or vertical
+       */
+      arrangement : 'horizontal',
+      /** @scratch /panels/terms/5
+       * chart:: table, bar or pie
+       */
+      chart       : 'bar',
+      /** @scratch /panels/terms/5
+       * counter_pos:: The location of the legend in respect to the chart, above or below.
+       */
+      counter_pos : 'above',
+      /** @scratch /panels/terms/5
+       * spyable:: Set spyable to false to disable the inspect button
+       */
+      spyable     : true,
+      /** @scratch /panels/terms/5
+       * ==== Queries
+       * queries object:: This object describes the queries to use on this panel.
+       * queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+       * queries.ids::: In +selected+ mode, which query ids are selected.
+       */
       queries     : {
         mode        : 'all',
         ids         : []
       },
-      field   : '_type',
-      exclude : [],
-      missing : true,
-      other   : true,
-      size    : 10,
-      order   : 'count',
-      style   : { "font-size": '10pt'},
-      donut   : false,
-      tilt    : false,
-      labels  : true,
-      arrangement : 'horizontal',
-      chart       : 'bar',
-      counter_pos : 'above',
-      spyable     : true
     };
     _.defaults($scope.panel,_d);
 

src/app/panels/text/module.js

@@ -1,10 +1,15 @@
-/*
+/** @scratch /panels/5
-  ## Text
+ * include::panels/text.asciidoc[]
-  ### Parameters
+ */
-  * mode :: 'text', 'html', 'markdown'
+
-  * content :: Content of the panel
+/** @scratch /panels/text/0
-  * style :: Hash containing css properties
+ * == text
-*/
+ * Status: *Stable*
+ *
+ * The text panel is used for displaying static text formated as markdown, sanitized html or as plain
+ * text.
+ *
+ */
 define([
   'angular',
   'app',
@@ -25,8 +30,15 @@ function (angular, app, _, require) {
 
     // Set and populate defaults
     var _d = {
-      status  : "Stable",
+      /** @scratch /panels/text/5
-      mode    : "markdown",
+       * === Parameters
+       *
+       * mode:: `html', `markdown' or `text'
+       */
+      mode    : "markdown", // 'html','markdown','text'
+      /** @scratch /panels/text/5
+       * content:: The content of your panel, written in the mark up specified in +mode+
+       */
       content : "",
       style: {},
     };

src/app/panels/trends/module.js

@@ -1,13 +1,16 @@
-/*
+/** @scratch /panels/5
+ * include::panels/trends.asciidoc[]
+ */
 
-  ## Trends
+/** @scratch /panels/trends/0
-
+ * == trends
-  ### Parameters
+ * Status: *Beta*
-  * style :: A hash of css styles
+ *
-  * arrangement :: How should I arrange the query results? 'horizontal' or 'vertical'
+ * A stock-ticker style representation of how queries are moving over time. For example, if the
-  * ago :: Date math formatted time to look back
+ * time is 1:10pm, your time picker was set to "Last 10m", and the "Time Ago" parameter was set to
-
+ * "1h", the panel would show how much the query results have changed since 12:00-12:10pm
-*/
+ *
+ */
 define([
   'angular',
   'app',
@@ -43,14 +46,32 @@ function (angular, app, _, kbn) {
 
     // Set and populate defaults
     var _d = {
+      /** @scratch /panels/trends/5
+       * === Parameters
+       *
+       * ago:: A date math formatted string describing the relative time period to compare the
+       * queries to.
+       */
+      ago     : '1d',
+      /** @scratch /panels/trends/5
+       * arrangement:: `horizontal' or `vertical'
+       */
+      arrangement : 'vertical',
+      /** @scratch /panels/trends/5
+       * spyable:: Set to false to disable the inspect icon
+       */
+      spyable: true,
+      /** @scratch /panels/trends/5
+       * ==== Queries
+       * queries object:: This object describes the queries to use on this panel.
+       * queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+       * queries.ids::: In +selected+ mode, which query ids are selected.
+       */
       queries     : {
         mode        : 'all',
         ids         : []
       },
       style   : { "font-size": '14pt'},
-      ago     : '1d',
-      arrangement : 'vertical',
-      spyable: true
     };
     _.defaults($scope.panel,_d);
 

src/config.js

@@ -1,7 +1,4 @@
 /** @scratch /configuration/config.js/1
- *
- * = Kibana =
- *
  * == Configuration ==
  * config.js is where you will find the core Kibana configuration. This file contains parameter that
  * must be set before kibana is run for the first time.
@@ -48,11 +45,9 @@ function (Settings) {
       'filtering',
       'timepicker',
       'text',
-      'fields',
       'hits',
       'dashcontrol',
       'column',
-      'derivequeries',
       'trends',
       'bettermap',
       'query',

tasks/default_task.js

@@ -1,4 +1,4 @@
 // Lint and build CSS
 module.exports = function(grunt) {
-  grunt.registerTask('default', ['jshint:source', 'less:src', 'docs']);
+  grunt.registerTask('default', ['docs','jshint:source', 'less:src']);
 };

tasks/options/scratchy.js

@@ -2,7 +2,7 @@ module.exports = function(config) {
   return {
     docs: {
       src: ['src/app/**/*.js','src/config.js'],
-      dest: config.docsDir,
+      dest: config.docsDir+"/kibana",
       options: {
         unslash: true,
         extension: '.asciidoc',