From 6898b44799469e544491839ae636720778783116 Mon Sep 17 00:00:00 2001 From: Catherine Liu Date: Thu, 20 Jun 2019 12:01:58 -0700 Subject: [PATCH] Added edits from PR #37614 --- .../canvas/canvas-function-reference.asciidoc | 41 +++++++++++-------- .../strings/functions/all.ts | 4 +- .../strings/functions/esdocs.ts | 4 +- .../strings/functions/essql.ts | 10 +++-- .../strings/functions/location.ts | 5 ++- .../strings/functions/markdown.ts | 16 +++++--- .../strings/functions/pointseries.ts | 2 +- .../strings/functions/urlparam.ts | 6 +-- .../canvas/public/functions/filters.js | 4 +- .../canvas/public/functions/timelion.js | 8 ++-- 10 files changed, 57 insertions(+), 43 deletions(-) diff --git a/docs/canvas/canvas-function-reference.asciidoc b/docs/canvas/canvas-function-reference.asciidoc index 215d8aca33ba0..6465b05fae153 100644 --- a/docs/canvas/canvas-function-reference.asciidoc +++ b/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 <> 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 <> 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: `{<>}` |=== @@ -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: `""` |=== diff --git a/x-pack/plugins/canvas/canvas_plugin_src/strings/functions/all.ts b/x-pack/plugins/canvas/canvas_plugin_src/strings/functions/all.ts index 6bbf9194d9907..272e2c2d33e12 100644 --- a/x-pack/plugins/canvas/canvas_plugin_src/strings/functions/all.ts +++ b/x-pack/plugins/canvas/canvas_plugin_src/strings/functions/all.ts @@ -11,11 +11,11 @@ import { FunctionFactory } from '../../functions/types'; export const help: FunctionHelp> = { 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', }), }, }; diff --git a/x-pack/plugins/canvas/canvas_plugin_src/strings/functions/esdocs.ts b/x-pack/plugins/canvas/canvas_plugin_src/strings/functions/esdocs.ts index 0af5f3718eb17..e2c769b083607 100644 --- a/x-pack/plugins/canvas/canvas_plugin_src/strings/functions/esdocs.ts +++ b/x-pack/plugins/canvas/canvas_plugin_src/strings/functions/esdocs.ts @@ -12,8 +12,8 @@ import { FunctionFactory } from '../../functions/types'; export const help: FunctionHelp> = { 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', }, diff --git a/x-pack/plugins/canvas/canvas_plugin_src/strings/functions/essql.ts b/x-pack/plugins/canvas/canvas_plugin_src/strings/functions/essql.ts index 645a46259a08c..a40ee3f33a347 100644 --- a/x-pack/plugins/canvas/canvas_plugin_src/strings/functions/essql.ts +++ b/x-pack/plugins/canvas/canvas_plugin_src/strings/functions/essql.ts @@ -11,20 +11,22 @@ import { FunctionFactory } from '../../functions/types'; export const help: FunctionHelp> = { 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: diff --git a/x-pack/plugins/canvas/canvas_plugin_src/strings/functions/location.ts b/x-pack/plugins/canvas/canvas_plugin_src/strings/functions/location.ts index 1500825bb982d..f09c10d2aad9e 100644 --- a/x-pack/plugins/canvas/canvas_plugin_src/strings/functions/location.ts +++ b/x-pack/plugins/canvas/canvas_plugin_src/strings/functions/location.ts @@ -12,8 +12,9 @@ import { FunctionFactory } from '../../functions/types'; export const help: FunctionHelp> = { 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: {}, }; diff --git a/x-pack/plugins/canvas/canvas_plugin_src/strings/functions/markdown.ts b/x-pack/plugins/canvas/canvas_plugin_src/strings/functions/markdown.ts index cefa708529904..ca6dd6785df26 100644 --- a/x-pack/plugins/canvas/canvas_plugin_src/strings/functions/markdown.ts +++ b/x-pack/plugins/canvas/canvas_plugin_src/strings/functions/markdown.ts @@ -12,21 +12,27 @@ import { FunctionFactory } from '../../functions/types'; export const help: FunctionHelp> = { 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', + }, }), }, }; diff --git a/x-pack/plugins/canvas/canvas_plugin_src/strings/functions/pointseries.ts b/x-pack/plugins/canvas/canvas_plugin_src/strings/functions/pointseries.ts index d99c7b2033038..c92043831d063 100644 --- a/x-pack/plugins/canvas/canvas_plugin_src/strings/functions/pointseries.ts +++ b/x-pack/plugins/canvas/canvas_plugin_src/strings/functions/pointseries.ts @@ -38,7 +38,7 @@ export const help: FunctionHelp> = { 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', }), }, }; diff --git a/x-pack/plugins/canvas/canvas_plugin_src/strings/functions/urlparam.ts b/x-pack/plugins/canvas/canvas_plugin_src/strings/functions/urlparam.ts index 13446323591e1..e095f12bd9de2 100644 --- a/x-pack/plugins/canvas/canvas_plugin_src/strings/functions/urlparam.ts +++ b/x-pack/plugins/canvas/canvas_plugin_src/strings/functions/urlparam.ts @@ -12,7 +12,7 @@ import { FunctionFactory } from '../../functions/types'; export const help: FunctionHelp> = { 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> = { }, }), 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', }, }), }, diff --git a/x-pack/plugins/canvas/public/functions/filters.js b/x-pack/plugins/canvas/public/functions/filters.js index e2798e70bad01..115b1cfd07776 100644 --- a/x-pack/plugins/canvas/public/functions/filters.js +++ b/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); diff --git a/x-pack/plugins/canvas/public/functions/timelion.js b/x-pack/plugins/canvas/public/functions/timelion.js index 737a17e78ecec..ac4dcd5981387 100644 --- a/x-pack/plugins/canvas/public/functions/timelion.js +++ b/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', }, },