core(i18n): add descriptions to UI strings (#5743)

lighthouse-core/audits/bootup-time.js

@@ -11,14 +11,21 @@ const {taskGroups} = require('../lib/task-groups');
 const i18n = require('../lib/i18n');
 
 const UIStrings = {
-  title: 'JavaScript boot-up time',
-  failureTitle: 'Reduce JavaScript boot-up time',
+  /** Title of a diagnostic audit that provides detail on the time spent executing javascript files during the load. This descriptive title is shown to users when the amount is acceptable and no user action is required. */
+  title: 'JavaScript execution time',
+  /** Title of a diagnostic audit that provides detail on the time spent executing javascript files during the load. This imperative title is shown to users when there is a significant amount of execution time that could be reduced. */
+  failureTitle: 'Reduce JavaScript execution time',
+  /** Description of a Lighthouse audit that tells the user that they should reduce the amount of time spent executing javascript and one method of doing so. This is displayed after a user expands the section to see more. No character length limits. 'Learn More' becomes link text to additional documentation. */
   description: 'Consider reducing the time spent parsing, compiling, and executing JS. ' +
     'You may find delivering smaller JS payloads helps with this. [Learn ' +
     'more](https://developers.google.com/web/tools/lighthouse/audits/bootup).',
+  /** Label for the total time column in a data table; entries will be the number of milliseconds spent executing per resource loaded by the page. */
   columnTotal: 'Total',
+  /** Label for a time column in a data table; entries will be the number of milliseconds spent evaluating script for every script loaded by the page. */
   columnScriptEval: 'Script Evaluation',
+  /** Label for a time column in a data table; entries will be the number of milliseconds spent parsing script files for every script loaded by the page. */
   columnScriptParse: 'Script Parse',
+  /** A message displayed in a Lighthouse audit result warning that Chrome extensions on the user's system substantially affected Lighthouse's measurements and instructs the user on how to run again without those extensions. */
   chromeExtensionsWarning: 'Chrome extensions negatively affected this page\'s load' +
     ' performance. Try auditing the page in incognito mode or from a clean Chrome profile.',
 };

lighthouse-core/audits/byte-efficiency/efficient-animated-content.js

@@ -13,7 +13,9 @@ const ByteEfficiencyAudit = require('./byte-efficiency-audit');
 const i18n = require('../../lib/i18n');
 
 const UIStrings = {
+  /** Imperative title of a Lighthouse audit that tells the user to use video formats rather than animated GIFs, which are wasteful. This is displayed in a list of audit titles that Lighthouse generates. */
   title: 'Use video formats for animated content',
+  /** Description of a Lighthouse audit that tells the user *why* they should use video instead of GIF format for delivering animated content. This is displayed after a user expands the section to see more. No character length limits. 'Learn More' becomes link text to additional documentation. */
   description: 'Large GIFs are inefficient for delivering animated content. Consider using ' +
     'MPEG4/WebM videos for animations and PNG/WebP for static images instead of GIF to save ' +
     'network bytes. [Learn more](https://developers.google.com/web/fundamentals/performance/optimizing-content-efficiency/replace-animated-gifs-with-video/)',

lighthouse-core/audits/byte-efficiency/offscreen-images.js

@@ -15,7 +15,9 @@ const URL = require('../../lib/url-shim');
 const i18n = require('../../lib/i18n');
 
 const UIStrings = {
+  /** Imperative title of a Lighthouse audit that tells the user to defer loading offscreen images. Offscreen images are images located outside of the visible browser viewport. As they are unseen by the user and slow down page load, they should be loaded later, closer to when the user is going to see them. This is displayed in a list of audit titles that Lighthouse generates. */
   title: 'Defer offscreen images',
+  /** Description of a Lighthouse audit that tells the user *why* they should defer loading offscreen images. Offscreen images are images located outside of the visible browser viewport. As they are unseen by the user and slow down page load, they should be loaded later, closer to when the user is going to see them. This is displayed after a user expands the section to see more. No character length limits. 'Learn More' becomes link text to additional documentation. */
   description:
     'Consider lazy-loading offscreen and hidden images after all critical resources have ' +
     'finished loading to lower time to interactive. ' +

lighthouse-core/audits/byte-efficiency/render-blocking-resources.js

@@ -27,7 +27,9 @@ const NetworkRequest = require('../../lib/network-request');
 const MINIMUM_WASTED_MS = 50;
 
 const UIStrings = {
+  /** Imperative title of a Lighthouse audit that tells the user to reduce or remove network resources that block the initial render of the page. This is displayed in a list of audit titles that Lighthouse generates. */
   title: 'Eliminate render-blocking resources',
+  /** Description of a Lighthouse audit that tells the user *why* they should reduce or remove network resources that block the initial render of the page. This is displayed after a user expands the section to see more. No character length limits. 'Learn More' becomes link text to additional documentation. */
   description: 'Resources are blocking the first paint of your page. Consider ' +
     'delivering critical JS/CSS inline and deferring all non-critical ' +
     'JS/styles. [Learn more](https://developers.google.com/web/tools/lighthouse/audits/blocking-resources).',

lighthouse-core/audits/byte-efficiency/total-byte-weight.js

@@ -9,8 +9,11 @@ const ByteEfficiencyAudit = require('./byte-efficiency-audit');
 const i18n = require('../../lib/i18n');
 
 const UIStrings = {
+  /** Title of a diagnostic audit that provides detail on large network resources required during page load. 'Payloads' is roughly equivalent to 'resources'. This descriptive title is shown to users when the amount is acceptable and no user action is required. */
   title: 'Avoids enormous network payloads',
+  /** Title of a diagnostic audit that provides detail on large network resources required during page load. 'Payloads' is roughly equivalent to 'resources'. This imperative title is shown to users when there is a significant amount of execution time that could be reduced. */
   failureTitle: 'Avoid enormous network payloads',
+  /** Description of a Lighthouse audit that tells the user *why* they should reduce the size of the network resources required by the page. This is displayed after a user expands the section to see more. No character length limits. 'Learn More' becomes link text to additional documentation. */
   description:
   'Large network payloads cost users real money and are highly correlated with ' +
   'long load times. [Learn ' +

lighthouse-core/audits/byte-efficiency/unminified-css.js

@@ -10,7 +10,9 @@ const UnusedCSSRules = require('./unused-css-rules');
 const i18n = require('../../lib/i18n');
 
 const UIStrings = {
+  /** Imperative title of a Lighthouse audit that tells the user to minify (remove whitespace) the page's CSS code. This is displayed in a list of audit titles that Lighthouse generates. */
   title: 'Minify CSS',
+  /** Description of a Lighthouse audit that tells the user *why* they should minify (remove whitespace) the page's CSS code. This is displayed after a user expands the section to see more. No character length limits. 'Learn More' becomes link text to additional documentation. */
   description: 'Minifying CSS files can reduce network payload sizes. ' +
   '[Learn more](https://developers.google.com/web/tools/lighthouse/audits/minify-css).',
 };

lighthouse-core/audits/byte-efficiency/unminified-javascript.js

@@ -10,7 +10,9 @@ const esprima = require('esprima');
 const i18n = require('../../lib/i18n');
 
 const UIStrings = {
+  /** Imperative title of a Lighthouse audit that tells the user to minify the page’s JS code to reduce file size. This is displayed in a list of audit titles that Lighthouse generates. */
   title: 'Minify JavaScript',
+  /** Description of a Lighthouse audit that tells the user *why* they should minify the page’s JS code to reduce file size. This is displayed after a user expands the section to see more. No character length limits. 'Learn More' becomes link text to additional documentation. */
   description: 'Minifying JavaScript files can reduce payload sizes and script parse time. ' +
     '[Learn more](https://developers.google.com/speed/docs/insights/MinifyResources).',
 };

lighthouse-core/audits/byte-efficiency/unused-css-rules.js

@@ -9,7 +9,9 @@ const ByteEfficiencyAudit = require('./byte-efficiency-audit');
 const i18n = require('../../lib/i18n');
 
 const UIStrings = {
+  /** Imperative title of a Lighthouse audit that tells the user to remove content from their CSS that isn’t needed immediately and instead load that content at a later time. This is displayed in a list of audit titles that Lighthouse generates. */
   title: 'Defer unused CSS',
+  /** Description of a Lighthouse audit that tells the user *why* they should defer loading any content in CSS that isn’t needed at page load. This is displayed after a user expands the section to see more. No word length limits. 'Learn More' becomes link text to additional documentation. */
   description: 'Remove unused rules from stylesheets to reduce unnecessary ' +
     'bytes consumed by network activity. ' +
     '[Learn more](https://developers.google.com/web/tools/lighthouse/audits/unused-css).',

lighthouse-core/audits/byte-efficiency/unused-javascript.js

@@ -9,7 +9,9 @@ const ByteEfficiencyAudit = require('./byte-efficiency-audit');
 const i18n = require('../../lib/i18n');
 
 const UIStrings = {
-  title: 'Unused JavaScript',
+  /** Imperative title of a Lighthouse audit that tells the user to remove JavaScript that is never evaluated during page load. This is displayed in a list of audit titles that Lighthouse generates. */
+  title: 'Remove unused JavaScript',
+  /** Description of a Lighthouse audit that tells the user *why* they should remove JavaScript that is never needed/evaluated by the browser. This is displayed after a user expands the section to see more. No character length limits. 'Learn More' becomes link text to additional documentation. */
   description: 'Remove unused JavaScript to reduce bytes consumed by network activity.',
 };
 

lighthouse-core/audits/byte-efficiency/uses-long-cache-ttl.js

@@ -15,11 +15,15 @@ const linearInterpolation = require('../../lib/statistics').linearInterpolation;
 const i18n = require('../../lib/i18n');
 
 const UIStrings = {
+  /** Title of a diagnostic audit that provides detail on the cache policy applies to the page's static assets. Cache refers to browser disk cache, which keeps old versions of network resources around for future use. This is displayed in a list of audit titles that Lighthouse generates. */
   title: 'Uses efficient cache policy on static assets',
+  /** Title of a diagnostic audit that provides details on the any page resources that could have been served with more efficient cache policies. Cache refers to browser disk cache, which keeps old versions of network resources around for future use. This imperative title is shown to users when there is a significant amount of assets served with poor cache policies. */
   failureTitle: 'Serve static assets with an efficient cache policy',
+  /** Description of a Lighthouse audit that tells the user *why* they need to adopt a long cache lifetime policy. This is displayed after a user expands the section to see more. No character length limits. 'Learn More' becomes link text to additional documentation. */
   description:
     'A long cache lifetime can speed up repeat visits to your page. ' +
     '[Learn more](https://developers.google.com/web/tools/lighthouse/audits/cache-policy).',
+  /** [ICU Syntax] Label for the audit identifying network resources with inefficient cache values. Clicking this will expand the audit to show the resources. */
   displayValue: `{itemCount, plural,
     =1 {1 resource found}
     other {# resources found}

lighthouse-core/audits/byte-efficiency/uses-optimized-images.js

@@ -14,7 +14,9 @@ const URL = require('../../lib/url-shim');
 const i18n = require('../../lib/i18n');
 
 const UIStrings = {
+  /** Imperative title of a Lighthouse audit that tells the user to encode images with optimization (better compression). This is displayed in a list of audit titles that Lighthouse generates. */
   title: 'Efficiently encode images',
+  /** Description of a Lighthouse audit that tells the user *why* they need to efficiently encode images. This is displayed after a user expands the section to see more. No character length limits. 'Learn More' becomes link text to additional documentation. */
   description: 'Optimized images load faster and consume less cellular data. ' +
   '[Learn more](https://developers.google.com/web/tools/lighthouse/audits/optimize-images).',
 };

lighthouse-core/audits/byte-efficiency/uses-responsive-images.js

@@ -19,7 +19,9 @@ const URL = require('../../lib/url-shim');
 const i18n = require('../../lib/i18n');
 
 const UIStrings = {
+  /** Imperative title of a Lighthouse audit that tells the user to resize images to match the display dimensions. This is displayed in a list of audit titles that Lighthouse generates. */
   title: 'Properly size images',
+  /** Description of a Lighthouse audit that tells the user *why* they need to serve appropriately sized images. This is displayed after a user expands the section to see more. No character length limits. 'Learn More' becomes link text to additional documentation. */
   description:
   'Serve images that are appropriately-sized to save cellular data ' +
   'and improve load time. ' +

lighthouse-core/audits/byte-efficiency/uses-text-compression.js

@@ -14,8 +14,10 @@ const URL = require('../../lib/url-shim');
 const i18n = require('../../lib/i18n');
 
 const UIStrings = {
+  /** Imperative title of a Lighthouse audit that tells the user to enable text compression (like gzip) in order to enhance the performance of a page. This is displayed in a list of audit titles that Lighthouse generates. */
   title: 'Enable text compression',
-  description: 'Text-based responses should be served with compression (gzip, deflate or' +
+  /** Description of a Lighthouse audit that tells the user *why* their text-based resources should be served with compression (like gzip). This is displayed after a user expands the section to see more. No character length limits. 'Learn More' becomes link text to additional documentation. */
+  description: 'Text-based resources should be served with compression (gzip, deflate or' +
     ' brotli) to minimize total network bytes.' +
     ' [Learn more](https://developers.google.com/web/tools/lighthouse/audits/text-compression).',
 };

lighthouse-core/audits/byte-efficiency/uses-webp-images.js

@@ -13,7 +13,9 @@ const URL = require('../../lib/url-shim');
 const i18n = require('../../lib/i18n');
 
 const UIStrings = {
+  /** Imperative title of a Lighthouse audit that tells the user to serve images in newer and more efficient image formats in order to enhance the performance of a page. A non-modern image format was designed 20+ years ago. This is displayed in a list of audit titles that Lighthouse generates. */
   title: 'Serve images in next-gen formats',
+  /** Description of a Lighthouse audit that tells the user *why* they should use newer and more efficient image formats. This is displayed after a user expands the section to see more. No character length limits. 'Learn More' becomes link text to additional documentation. */
   description: 'Image formats like JPEG 2000, JPEG XR, and WebP often provide better ' +
     'compression than PNG or JPEG, which means faster downloads and less data consumption. ' +
     '[Learn more](https://developers.google.com/web/tools/lighthouse/audits/webp).',

lighthouse-core/audits/critical-request-chains.js

@@ -9,12 +9,15 @@ const Audit = require('./audit');
 const i18n = require('../lib/i18n');
 
 const UIStrings = {
-  title: 'Minimize Critical Request Chains',
+  /** Imperative title of a Lighthouse audit that tells the user to reduce the depth of critical network requests to enhance initial load of a page. Critical request chains are series of dependent network requests that are important for page rendering. For example, here's a 4-request-deep chain: The biglogo.jpg image is required, but is requested via the styles.css style code, which is requested by the initialize.js javascript, which is requested by the page's HTML. This is displayed in a list of audit titles that Lighthouse generates. */
+  title: 'Minimize Critical Requests Depth',
+  /** Description of a Lighthouse audit that tells the user *why* they should reduce the depth of critical network requests to enhance initial load of a page . This is displayed after a user expands the section to see more. No character length limits. 'Learn More' becomes link text to additional documentation. */
   description: 'The Critical Request Chains below show you what resources are ' +
       'issued with a high priority. Consider reducing ' +
       'the length of chains, reducing the download size of resources, or ' +
       'deferring the download of unnecessary resources to improve page load. ' +
       '[Learn more](https://developers.google.com/web/tools/lighthouse/audits/critical-request-chains).',
+  /** [ICU Syntax] Label for an audit identifying the number of sequences of dependent network requests used to load the page. */
   displayValue: `{itemCount, plural,
     =1 {1 chain found}
     other {# chains found}

lighthouse-core/audits/dobetterweb/dom-size.js

@@ -21,17 +21,24 @@ const MAX_DOM_TREE_WIDTH = 60;
 const MAX_DOM_TREE_DEPTH = 32;
 
 const UIStrings = {
+  /** Title of a diagnostic audit that provides detail on the size of the web page's DOM. The size of a DOM is characterized by the total number of DOM nodes and greatest DOM depth. This descriptive title is shown to users when the amount is acceptable and no user action is required. */
   title: 'Avoids an excessive DOM size',
+  /** Title of a diagnostic audit that provides detail on the size of the web page's DOM. The size of a DOM is characterized by the total number of DOM nodes and greatest DOM depth. This imperative title is shown to users when there is a significant amount of execution time that could be reduced. */
   failureTitle: 'Avoid an excessive DOM size',
+  /** Description of a Lighthouse audit that tells the user *why* they should reduce the size of the web page's DOM. The size of a DOM is characterized by the total number of DOM nodes and greatest DOM depth. This is displayed after a user expands the section to see more. No character length limits. 'Learn More' becomes link text to additional documentation. */
   description: 'Browser engineers recommend pages contain fewer than ' +
     `~${MAX_DOM_NODES.toLocaleString()} DOM nodes. The sweet spot is a tree ` +
     `depth < ${MAX_DOM_TREE_DEPTH} elements and fewer than ${MAX_DOM_TREE_WIDTH} ` +
     'children/parent element. A large DOM can increase memory usage, cause longer ' +
     '[style calculations](https://developers.google.com/web/fundamentals/performance/rendering/reduce-the-scope-and-complexity-of-style-calculations), ' +
     'and produce costly [layout reflows](https://developers.google.com/speed/articles/reflow). [Learn more](https://developers.google.com/web/tools/lighthouse/audits/dom-size).',
+  /** Label for the total number of DOM nodes found in the page. */
   columnDOMNodes: 'Total DOM Nodes',
+  /** Label for the numeric value of the maximum depth in the page's DOM tree. */
   columnDOMDepth: 'Maximum DOM Depth',
+  /** Label for the value of the maximum number of children any DOM node in the page has. */
   columnDOMWidth: 'Maximum Children',
+  /** [ICU Syntax] Label for an audit identifying the number of DOM nodes found in the page. */
   displayValue: `{itemCount, plural,
     =1 {1 node}
     other {# nodes}