Added edits from PR #37614

docs/canvas/canvas-function-reference.asciidoc

@@ -535,7 +535,7 @@ Default: `all`
 [[esdocs_fn]]
 === `esdocs`
 
-Queries {es} and gets back raw documents. Specify the fields you want to receive, 
+Queries {es} and returns raw documents. Specify the fields you want to receive, 
 especially if you are asking for a lot of rows.
 
 *Accepts:* `filter`
@@ -586,7 +586,7 @@ Default: `100`
 [[essql_fn]]
 === `essql`
 
-Specifies an {es} SQL.
+Specifies an {es} SQL query.
 
 *Accepts:* `filter`
 
@@ -602,9 +602,15 @@ Alias: `q`, `query`
 
 |`count`
 |`number`
-|The number of documents to retrieve
+|The number of documents to retrieve. Smaller numbers perform better.
 
 Default: `1000`
+
+|`timezone`
+|`string`
+|The timezone to use for date operations, valid ISO8601 formats and UTC offsets both work.
+
+Default: `UTC`
 |===
 
 *Returns:* `datatable`
@@ -673,7 +679,7 @@ and a `false` value removes it.
 [[filters_fn]]
 === `filters`
 
-Collects element filters on the workpad, usually to provide them to a data source.
+Aggregates element filters from the workpad for use elsewhere, usually a data source.
 
 *Accepts:* `null`
 
@@ -691,7 +697,7 @@ Alias: `group`
 
 Alias: `nogroup`, `nogroups`
 |`boolean`
-|Don't include filters that belong to groups
+|Exclude filters that belong to a filter group
 
 Default: `false`
 |===
@@ -984,8 +990,8 @@ data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW
 [[location_fn]]
 === `location`
 
-Uses the browser's location functionality to get your current location. Usually 
-quite slow, but fairly accurate.
+Find your current location using the Geolocation API of the browser. Performance can vary, but is fairly accurate. 
+See: https://developer.mozilla.org/en-US/docs/Web/API/Navigator/geolocation.
 
 *Accepts:* `null`
 
@@ -1072,7 +1078,7 @@ Alias: `exp`, `fn`, `function`
 [[markdown_fn]]
 === `markdown`
 
-Adds an element for rendering Markdown text. Great for single numbers, metrics, or paragraphs of text.
+Adds an element that renders Markdown text. TIP: Use the <<markdown_fn>> function for single numbers, metrics, and paragraphs of text.
 
 *Accepts:* `datatable`, `null`
 
@@ -1084,14 +1090,13 @@ Adds an element for rendering Markdown text. Great for single numbers, metrics,
 
 Alias: `expression`, `content`
 |`string`
-|A `string` containing Markdown. You can pass this multiple 
-times to achieve concatenation 
+|A string of text that contains Markdown. To concatenate, pass the <<string_fn>> function multiple times.
 
 Default: `""`
 
 |`font`
 |`style`
-|Font settings. Technically, you can put other styles in here too 
+|Set the CSS font properties, (e.g. font-family, font-weight). Other CSS styles can be included as well.
 
 Default: `{<<font_fn>>}`
 |===
@@ -1409,7 +1414,7 @@ then deduplicated by those keys using the specified TinyMath function.
 
 |`text`
 |`string`
-|For use in charts that support it, the text to show in the mark
+|For elements that support it, the text to show in the mark
 |===
 
 *Returns:* `pointseries`
@@ -2054,25 +2059,25 @@ Default: `".es(*)"`
 
 |`interval`
 |`string`
-|Bucket interval for the time series 
+|The bucket interval for the time series 
 
 Default: `"auto"`
 
 |`from`
 |`string`
-|{es} `datemath` string for the start of the time range 
+|The {es} `datemath` string for the start of the time range.
 
 Default: `"now-1y"`
 
 |`to`
 |`string`
-|{es} date math `string` for the end of the time range 
+|The {es} `datemath` string for the end of the time range.
 
 Default: `"now"`
 
 |`timezone`
 |`string`
-|Time zone for the time range 
+|Timezone for the time range. See [Moment Timezone](https://momentjs.com/timezone/).
 
 Default: `"UTC"`
 |===
@@ -2108,7 +2113,7 @@ Alias: `type`
 [[urlparam_fn]]
 === `urlparam`
 
-Accesses URL parameters and use them in expressions. This will always return a `string`.
+Accesses URL parameters to use in expressions, (e.g. https://localhost:5601/app/canvas?myVar=20) and returns them as a string.
 
 *Accepts:* `null`
 
@@ -2124,7 +2129,7 @@ Aliases: `var`, `variable`
 
 |`default`
 |`string`
-|Return this `string` if the url parameter is not defined  
+|If the URL parameter is not present, return this string instead.
 
 Default: `""`
 |===

x-pack/plugins/canvas/canvas_plugin_src/strings/functions/all.ts

@@ -11,11 +11,11 @@ import { FunctionFactory } from '../../functions/types';
 
 export const help: FunctionHelp<FunctionFactory<typeof all>> = {
   help: i18n.translate('xpack.canvas.functions.allHelpText', {
-    defaultMessage: 'Return true if all of the conditions are true',
+    defaultMessage: 'Return `true` if all of the conditions are `true`. See also `any`.',
   }),
   args: {
     condition: i18n.translate('xpack.canvas.functions.all.args.conditionHelpText', {
-      defaultMessage: 'One or more conditions to check',
+      defaultMessage: 'The conditions to check',
     }),
   },
 };

x-pack/plugins/canvas/canvas_plugin_src/strings/functions/esdocs.ts

@@ -12,8 +12,8 @@ import { FunctionFactory } from '../../functions/types';
 export const help: FunctionHelp<FunctionFactory<typeof esdocs>> = {
   help: i18n.translate('xpack.canvas.functions.esdocsHelpText', {
     defaultMessage:
-      'Query {es} and get back raw documents. We recommend you specify the fields you want, ' +
-      'especially if you are going to ask for a lot of rows',
+      'Query {es} and returns raw documents. Specify the fields you want to receive, ' +
+      'especially if you are asking for a lot of rows',
     values: {
       es: 'elasticsearch',
     },

x-pack/plugins/canvas/canvas_plugin_src/strings/functions/essql.ts

@@ -11,20 +11,22 @@ import { FunctionFactory } from '../../functions/types';
 
 export const help: FunctionHelp<FunctionFactory<typeof essql>> = {
   help: i18n.translate('xpack.canvas.functions.essqlHelpText', {
-    defaultMessage: '{essql}',
+    defaultMessage: 'Queries {es} using {es} {sql}',
     values: {
-      essql: 'Elasticsearch SQL',
+      es: 'Elasticsearch',
+      sql: 'SQL',
     },
   }),
   args: {
     query: i18n.translate('xpack.canvas.functions.essql.args.queryHelpText', {
-      defaultMessage: '{sql} query',
+      defaultMessage: 'An {es} {sql} query',
       values: {
+        es: 'Elasticsearch',
         sql: 'SQL',
       },
     }),
     count: i18n.translate('xpack.canvas.functions.essql.args.countHelpText', {
-      defaultMessage: 'The number of docs to pull back. Smaller numbers perform better',
+      defaultMessage: 'The number of documents to retrieve. Smaller numbers perform better.',
     }),
     timezone: i18n.translate('xpack.canvas.functions.essql.args.timezoneHelpText', {
       defaultMessage:

x-pack/plugins/canvas/canvas_plugin_src/strings/functions/location.ts

@@ -12,8 +12,9 @@ import { FunctionFactory } from '../../functions/types';
 export const help: FunctionHelp<FunctionFactory<typeof location>> = {
   help: i18n.translate('xpack.canvas.functions.locationHelpText', {
     defaultMessage:
-      "Use the browser's location functionality to get your current location. " +
-      'Usually quite slow, but fairly accurate',
+      'Find your current location using the Geolocation API of the browser. ' +
+      'Performance can vary, but is fairly accurate. ' +
+      'See https://developer.mozilla.org/en-US/docs/Web/API/Navigator/geolocation',
   }),
   args: {},
 };

x-pack/plugins/canvas/canvas_plugin_src/strings/functions/markdown.ts

@@ -12,21 +12,27 @@ import { FunctionFactory } from '../../functions/types';
 export const help: FunctionHelp<FunctionFactory<typeof markdown>> = {
   help: i18n.translate('xpack.canvas.functions.markdownHelpText', {
     defaultMessage:
-      'An element for rendering {markdown} text. Great for single numbers, metrics or paragraphs of text.',
+      'Adds an element that renders {markdown} text. TIP: Use the `markdown` function for single numbers, metrics, and paragraphs of text.',
     values: {
-      markdown: 'markdown',
+      markdown: 'Markdown',
     },
   }),
   args: {
     content: i18n.translate('xpack.canvas.functions.markdown.args.contentHelpText', {
       defaultMessage:
-        'A {markdown} expression. You can pass this multiple times to achieve concatenation',
+        'A string of text that contains {markdown}. To concatenate, pass the `string` function multiple times.',
       values: {
-        markdown: 'markdown',
+        markdown: 'Markdown',
       },
     }),
     font: i18n.translate('xpack.canvas.functions.markdown.args.fontHelpText', {
-      defaultMessage: 'Font settings. Technically, you can add other styles in here as well',
+      defaultMessage:
+        'Set the {css} font properties, (e.g. {fontFamily}, {fontWeight}). Other {css} styles can be included as well.',
+      values: {
+        css: 'CSS',
+        fontFamily: 'font-family',
+        fontWeight: 'font-weight',
+      },
     }),
   },
 };

x-pack/plugins/canvas/canvas_plugin_src/strings/functions/pointseries.ts

@@ -38,7 +38,7 @@ export const help: FunctionHelp<FunctionFactory<typeof pointseries>> = {
       defaultMessage: 'For elements that support it, the size of the marks',
     }),
     text: i18n.translate('xpack.canvas.functions.pointseries.args.textHelpText', {
-      defaultMessage: 'For use in charts that support it, the text to show in the mark',
+      defaultMessage: 'For elements that support it, the text to show in the mark',
     }),
   },
 };

x-pack/plugins/canvas/canvas_plugin_src/strings/functions/urlparam.ts

@@ -12,7 +12,7 @@ import { FunctionFactory } from '../../functions/types';
 export const help: FunctionHelp<FunctionFactory<typeof urlparam>> = {
   help: i18n.translate('xpack.canvas.functions.urlparamHelpText', {
     defaultMessage:
-      'Access {url} parameters and use them in expressions. Eg {example}. This will always return a string',
+      'Accesses {url} parameters to use in expressions, (e.g. {example}) and returns them as a string.',
     values: {
       url: 'URL',
       example: 'https://localhost:5601/app/canvas?myVar=20',
@@ -26,9 +26,9 @@ export const help: FunctionHelp<FunctionFactory<typeof urlparam>> = {
       },
     }),
     default: i18n.translate('xpack.canvas.functions.urlparam.args.defaultHelpText', {
-      defaultMessage: 'Return this string if the {url} parameter is not defined',
+      defaultMessage: 'If the {url} parameter is not present, return this string instead.',
       values: {
-        url: 'url',
+        url: 'URL',
       },
     }),
   },

x-pack/plugins/canvas/public/functions/filters.js

@@ -48,11 +48,11 @@ export const filters = () => ({
     ungrouped: {
       aliases: ['nogroup', 'nogroups'],
       types: ['boolean'],
-      help: "Don't include filters that belong to groups",
+      help: 'Exclude filters that belong to a filter group',
       default: false,
     },
   },
-  help: 'Collect element filters on the workpad, usually to provide them to a data source',
+  help: 'Aggregates element filters from the workpad for use elsewhere, usually a data source.',
   fn: (_, { group, ungrouped }) => {
     const filterList = getFiltersByGroup(getGlobalFilters(getState()), group, ungrouped);
 

x-pack/plugins/canvas/public/functions/timelion.js

@@ -23,22 +23,22 @@ export const timelion = () => ({
     },
     interval: {
       types: ['string'],
-      help: 'Bucket interval for the time series',
+      help: 'The bucket interval for the time series.',
       default: 'auto',
     },
     from: {
       type: ['string'],
-      help: 'Elasticsearch date math string for the start of the time range',
+      help: 'The Elasticsearch `datemath` string for the start of the time range.',
       default: 'now-1y',
     },
     to: {
       type: ['string'],
-      help: 'Elasticsearch date math string for the end of the time range',
+      help: 'The Elasticsearch `datemath` string for the end of the time range.',
       default: 'now',
     },
     timezone: {
       type: ['string'],
-      help: 'Timezone for the time range',
+      help: 'Timezone for the time range. See [Moment Timezone](https://momentjs.com/timezone/)',
       default: 'UTC',
     },
   },