Initial descriptions.

GoogleChrome · paulirish · Jun 25, 2019 · May 31, 2019 · May 31, 2019 · May 31, 2019
commit 197dc4bbf90b2a0bafc45114cb9df78f1aa74baf
diff --git a/lighthouse-core/audits/deprecations.js b/lighthouse-core/audits/deprecations.js
@@ -15,15 +15,21 @@ const Audit = require('./audit.js');
 const i18n = require('../lib/i18n/i18n.js');
 
 const UIStrings = {
+  /** Title of a Lighthouse audit that provides detail on the use of deprecated APIs. This descriptive title is shown to users when the site does not use deprecated APIs. */
   title: 'Avoids deprecated APIs',
+  /** Title of a Lighthouse audit that provides detail on the use of deprecated APIs. This descriptive title is shown to users when the site uses deprecated APIs. */
   failureTitle: 'Uses deprecated APIs',
+  /** Description of a Lighthouse audit that tells the user why they should not use deprecated APIs on their site. 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: 'Deprecated APIs will eventually be removed from the browser. ' +
       '[Learn more](https://www.chromestatus.com/features#deprecated).',
+  /** [ICU Syntax] Label for the audit identifying the number of warnings generated by using deprecated APIs. */
   displayValue: `{itemCount, plural,
     =1 {1 warning found}
     other {# warnings found}
     }`,
+  /** Table column header for the deprecation or warning generated by the site. */
   columnDeprecate: 'Deprecation / Warning',
+  /** Table column header for line that is using a deprecated API on the site. */
   columnLine: 'Line',
 };
 

diff --git a/lighthouse-core/audits/dobetterweb/appcache-manifest.js b/lighthouse-core/audits/dobetterweb/appcache-manifest.js
@@ -14,10 +14,14 @@ const Audit = require('../audit.js');
 const i18n = require('../../lib/i18n/i18n.js');
 
 const UIStrings = {
+  /** Title of a Lighthouse audit that provides detail on the use of the Application Cache API. This descriptive title is shown to users when they do not use the Application Cache API. */
   title: 'Avoids Application Cache',
+  /** Title of a Lighthouse audit that provides detail on the use of the Application Cache API. This descriptive title is shown to users when they do use the Application Cache API, which is considered bad practice. */
   failureTitle: 'Uses Application Cache',
+  /** Description of a Lighthouse audit that tells the user why they should not use the Application Cache API. 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: 'Application Cache is deprecated. ' +
     '[Learn more](https://developers.google.com/web/tools/lighthouse/audits/appcache).',
+  /** Label for the audit identifying uses of the Application Cache. */
   displayValue: 'Found "{AppCacheManifest}"',
 };
 

diff --git a/lighthouse-core/audits/dobetterweb/doctype.js b/lighthouse-core/audits/dobetterweb/doctype.js
@@ -9,14 +9,21 @@ const Audit = require('../audit.js');
 const i18n = require('../../lib/i18n/i18n.js');
 
 const UIStrings = {
+  /** Title of a Lighthouse audit that provides detail on the doctype of a site. This descriptive title is shown to users when the site's doctype is set to HTML. */
   title: 'Page has the HTML doctype',
+  /** Title of a Lighthouse audit that provides detail on the doctype of a site. This descriptive title is shown to users when the site's doctype is not set to HTML. */
   failureTitle: 'Page is missing the HTML doctype',
+  /** Description of a Lighthouse audit that tells the user why they should set the doctype as HTML. 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: 'Specifying a doctype prevents the browser ' +
     'from switching to quirks-mode. Read more on the ' +
     '[MDN Web Docs page](https://developer.mozilla.org/en-US/docs/Glossary/Doctype)',
+  /** Explanatory message stating that the document has no doctype. */
   explanationNoDoctype: 'Document must contain a doctype',
+  /** Explanatory message stating that the publicId field is not empty. */
   explanationPublicId: 'Expected publicId to be an empty string',
+  /** Explanatory message stating that the systemId field is not empty. */
   explanationSystemId: 'Expected systemId to be an empty string',
+  /** Explanatory message stating that the doctype is set, but is not "html" and is therefore invalid. */
   explanationBadDoctype: 'Doctype name must be the lowercase string `html`',
 };
 

diff --git a/lighthouse-core/audits/dobetterweb/external-anchors-use-rel-noopener.js b/lighthouse-core/audits/dobetterweb/external-anchors-use-rel-noopener.js
@@ -10,14 +10,20 @@ const Audit = require('../audit.js');
 const i18n = require('../../lib/i18n/i18n.js');
 
 const UIStrings = {
+  /** Title of a Lighthouse audit that provides detail on the cross-origin links that a site contains, and whether they can be considered safe. This descriptive title is shown to users when all links are safe. */
   title: 'Links to cross-origin destinations are safe',
+  /** Title of a Lighthouse audit that provides detail on the cross-origin links that a site contains, and whether they can be considered safe. This descriptive title is shown to users when not all links can be considered safe. */
   failureTitle: 'Links to cross-origin destinations are unsafe',
+  /** Description of a Lighthouse audit that tells the user why and how they should secure cross-origin links. 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: 'Add `rel="noopener"` or `rel="noreferrer"` to any external links to improve ' +
     'performance and prevent security vulnerabilities. ' +
     '[Learn more](https://developers.google.com/web/tools/lighthouse/audits/noopener).',
+  /** Warning that some links' destinations cannot be determined and therefor neither can their safety. */
   warning: 'Unable to determine the destination for anchor ({anchorHTML}). ' +
     'If not used as a hyperlink, consider removing target=_blank.',
+  /** Table column header for the target of a URL. */
   columnTarget: 'Target',
+  /** Table column header for the `rel=` value from the link. */
   columnRel: 'Rel',
 };
 

diff --git a/lighthouse-core/audits/dobetterweb/geolocation-on-start.js b/lighthouse-core/audits/dobetterweb/geolocation-on-start.js
@@ -15,8 +15,11 @@ const ViolationAudit = require('../violation-audit.js');
 const i18n = require('../../lib/i18n/i18n.js');
 
 const UIStrings = {
+  /** Title of a Lighthouse audit that provides detail on geolocation permissions requests. This descriptive title is shown to users when the page does not ask for geolocation permissions on load. */
   title: 'Avoids requesting the geolocation permission on page load',
+  /** Title of a Lighthouse audit that provides detail on geolocation permissions requests. This descriptive title is shown to users when the page does ask for geolocation permissions on load. */
   failureTitle: 'Requests the geolocation permission on page load',
+  /** Description of a Lighthouse audit that tells the user why they should not ask for geolocation permissions on load. 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: 'Users are mistrustful of or confused by sites that request their ' +
     'location without context. Consider tying the request to user gestures instead. ' +
     '[Learn more](https://developers.google.com/web/tools/lighthouse/audits/geolocation-on-load).',

diff --git a/lighthouse-core/audits/dobetterweb/js-libraries.js b/lighthouse-core/audits/dobetterweb/js-libraries.js
@@ -14,9 +14,13 @@ const Audit = require('../audit.js');
 const i18n = require('../../lib/i18n/i18n.js');
 
 const UIStrings = {
+  /** Title of a Lighthouse audit that provides detail on the Javascript libraries that are used on a site. */
   title: 'Detected JavaScript libraries',
+  /** Description of a Lighthouse audit that tells the user what this audit is detecting. This is displayed after a user expands the section to see more. No character length limits. */
   description: 'All front-end JavaScript libraries detected on the page.',
+  /** Table column header for the name of the Javascript library. */
   columnName: 'Name',
+  /** Table column header for the version of the detected Javascript library. */
   columnVersion: 'Version',
 };
 

diff --git a/lighthouse-core/audits/dobetterweb/no-document-write.js b/lighthouse-core/audits/dobetterweb/no-document-write.js
@@ -14,8 +14,11 @@ const ViolationAudit = require('../violation-audit.js');
 const i18n = require('../../lib/i18n/i18n.js');
 
 const UIStrings = {
+  /** Title of a Lighthouse audit that provides detail on the page's use of the `Document.write` API. This descriptive title is shown to users when the site does not use `Document.write`. */
   title: 'Avoids `document.write()`',
+  /** Title of a Lighthouse audit that provides detail on the page's use of the `Document.write` API. This descriptive title is shown to users when the site does use `Document.write`. */
   failureTitle: 'Uses `document.write()`',
+  /** Description of a Lighthouse audit that tells the user why they should avoid `Document.write`. 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: 'For users on slow connections, external scripts dynamically injected via ' +
       '`document.write()` can delay page load by tens of seconds. ' +
       '[Learn more](https://developers.google.com/web/tools/lighthouse/audits/document-write).',

diff --git a/lighthouse-core/audits/dobetterweb/no-vulnerable-libraries.js b/lighthouse-core/audits/dobetterweb/no-vulnerable-libraries.js
@@ -19,19 +19,26 @@ const snykDatabase = require('../../../third-party/snyk/snapshot.json');
 const i18n = require('../../lib/i18n/i18n.js');
 
 const UIStrings = {
+  /** Title of a Lighthouse audit that provides detail on Javascript libraries the site uses. This descriptive title is shown to users when all Javascript libraries are free of known security vulnerabilities. */
   title: 'Avoids front-end JavaScript libraries' +
     ' with known security vulnerabilities',
+  /** Title of a Lighthouse audit that provides detail on Javascript libraries the site uses. This descriptive title is shown to users when some detected Javascript libraries have known security vulnerabilities. */
   failureTitle: 'Includes front-end JavaScript libraries' +
     ' with known security vulnerabilities',
+  /** Description of a Lighthouse audit that tells the user why they should be concerned about the third party Javascript libraries that they use. 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: 'Some third-party scripts may contain known security vulnerabilities ' +
     'that are easily identified and exploited by attackers. ' +
     '[Learn more](https://developers.google.com/web/tools/lighthouse/audits/vulnerabilities).',
+  /** [ICU Syntax] Label for the audit identifying the number of vulnerable Javascript libraries found. */
   displayValue: `{itemCount, plural,
     =1 {1 vulnerability detected}
     other {# vulnerabilities detected}
     }`,
+  /** Table column header for the version of the Javascript library found. */
   columnVersion: 'Library Version',
+  /** Table column header for the count of vulnerabilities found. */
   columnVuln: 'Vulnerability Count',
+  /** Table column header for the severity of the vulnerabilities found in the detected Javascript libraries. */
   columnSeverity: 'Highest Severity',
 };
 

diff --git a/lighthouse-core/audits/dobetterweb/notification-on-start.js b/lighthouse-core/audits/dobetterweb/notification-on-start.js
@@ -15,8 +15,11 @@ const ViolationAudit = require('../violation-audit.js');
 const i18n = require('../../lib/i18n/i18n.js');
 
 const UIStrings = {
+  /** Title of a Lighthouse audit that provides detail on the sites' notification permission requests. This descriptive title is shown to users when the page does not ask for notification permission on load. */
   title: 'Avoids requesting the notification permission on page load',
+  /** Title of a Lighthouse audit that provides detail on the sites' notification permission requests. This descriptive title is shown to users when the page does ask for notification permission on load. */
   failureTitle: 'Requests the notification permission on page load',
+  /** Description of a Lighthouse audit that tells the user why they should not ask for notification permission on load. 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: 'Users are mistrustful of or confused by sites that request to send ' +
       'notifications without context. Consider tying the request to user gestures ' +
       'instead. [Learn more](https://developers.google.com/web/tools/lighthouse/audits/notifications-on-load).',

diff --git a/lighthouse-core/audits/dobetterweb/password-inputs-can-be-pasted-into.js b/lighthouse-core/audits/dobetterweb/password-inputs-can-be-pasted-into.js
@@ -9,10 +9,14 @@ const Audit = require('../audit.js');
 const i18n = require('../../lib/i18n/i18n.js');
 
 const UIStrings = {
+  /** Title of a Lighthouse audit that provides detail on the ability to paste into password fields. This descriptive title is shown to users when a site allows pasting of content into password fields. */
   title: 'Allows users to paste into password fields',
+  /** Title of a Lighthouse audit that provides detail on the ability to paste into password fields. This descriptive title is shown to users when a site does not allow pasting of content into password fields. */
   failureTitle: 'Prevents users to paste into password fields',
+  /** Description of a Lighthouse audit that tells the user why they should allow pasting of content into password fields. 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: 'Preventing password pasting undermines good security policy. ' +
       '[Learn more](https://developers.google.com/web/tools/lighthouse/audits/password-pasting).',
+  /** Table column header for the HTML elements that do not allow pasting of content. */
   columnFailingElem: 'Failing Elements',
 };
 

diff --git a/lighthouse-core/audits/dobetterweb/uses-http2.js b/lighthouse-core/audits/dobetterweb/uses-http2.js
@@ -17,14 +17,19 @@ const NetworkRecords = require('../../computed/network-records.js');
 const i18n = require('../../lib/i18n/i18n.js');
 
 const UIStrings = {
+  /** Title of a Lighthouse audit that provides detail on whether the site uses HTTP/2 for its requested resources. This descriptive title is shown to users when the site uses HTTP/2 for its requests. */
   title: 'Uses HTTP/2 for its own resources',
+  /** Title of a Lighthouse audit that provides detail on whether the site uses HTTP/2 for its requested resources. This descriptive title is shown to users when the site does not use HTTP/2 for its requests. */
   failureTitle: 'Does not use HTTP/2 for all of its resources',
+  /** Description of a Lighthouse audit that tells the user why they should use HTTP/2. 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: 'HTTP/2 offers many benefits over HTTP/1.1, including binary headers, ' +
       'multiplexing, and server push. [Learn more](https://developers.google.com/web/tools/lighthouse/audits/http2).',
+  /** [ICU Syntax] Label for the audit identifying the number of requests that were not served with HTTP/2. */
   displayValue: `{itemCount, plural,
     =1 {1 request not served via HTTP/2}
     other {# requests not served via HTTP/2}
     }`,
+  /** Table column header for the HTTP Protocol used in a request. */
   columnProtocol: 'Protocol',
 };
 

diff --git a/lighthouse-core/audits/dobetterweb/uses-passive-event-listeners.js b/lighthouse-core/audits/dobetterweb/uses-passive-event-listeners.js
@@ -15,8 +15,11 @@ const ViolationAudit = require('../violation-audit.js');
 const i18n = require('../../lib/i18n/i18n.js');
 
 const UIStrings = {
+  /** Title of a Lighthouse audit that provides detail on the site's use of passive listeners used to improve the scrolling performance of the site. This descriptive title is shown to users when the site does use passive listeners. */
   title: 'Uses passive listeners to improve scrolling performance',
+  /** Title of a Lighthouse audit that provides detail on the site's use of passive listeners used to improve the scrolling performance of the site. This descriptive title is shown to users when the site does not use passive listeners. */
   failureTitle: 'Does not use passive listeners to improve scrolling performance',
+  /** Description of a Lighthouse audit that tells the user why they should use passive listeners on the site. 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 marking your touch and wheel event listeners as `passive` ' +
       'to improve your page\'s scroll performance. ' +
       '[Learn more](https://developers.google.com/web/tools/lighthouse/audits/passive-event-listeners).',

diff --git a/lighthouse-core/audits/errors-in-console.js b/lighthouse-core/audits/errors-in-console.js
@@ -14,10 +14,14 @@ const Audit = require('./audit.js');
 const i18n = require('../lib/i18n/i18n.js');
 
 const UIStrings = {
+  /** Title of a Lighthouse audit that provides detail on browser errors. This descriptive title is shown to users when no browser errors were logged into the devtools console. */
   title: 'No browser errors logged to the console',
+  /** Title of a Lighthouse audit that provides detail on browser errors. This descriptive title is shown to users when browser errors were logged into the devtools console. */
+  failureTitle: 'Browser errors were logged to the console',
+  /** Description of a Lighthouse audit that tells the user why they should not log errors into the console. This is displayed after a user expands the section to see more. No character length limits. */
   description: 'Errors logged to the console indicate unresolved problems. ' +
     'They can come from network request failures and other browser concerns.',
-  failureTitle: 'Browser errors were logged to the console',
+  /** Table column header for the description of the browser error that was logged. */
   columnDesc: 'Description',
 };
 

diff --git a/lighthouse-core/audits/image-aspect-ratio.js b/lighthouse-core/audits/image-aspect-ratio.js
@@ -16,12 +16,18 @@ const URL = require('../lib/url-shim.js');
 const i18n = require('../lib/i18n/i18n.js');
 
 const UIStrings = {
+  /** Title of a Lighthouse audit that provides detail on the aspect ratios of all images on a site. This descriptive title is shown to users when all images use correct aspect ratios. */
   title: 'Displays images with correct aspect ratio',
+  /** Title of a Lighthouse audit that provides detail on the aspect ratios of all images on a site. This descriptive title is shown to users when not all images use correct aspect ratios. */
   failureTitle: 'Displays images with incorrect aspect ratio',
+  /** Description of a Lighthouse audit that tells the user why they should maintain the correct aspect ratios for all 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: 'Image display dimensions should match natural aspect ratio. ' +
     '[Learn more](https://developers.google.com/web/tools/lighthouse/audits/aspect-ratio).',
+  /** Warning that the sizing information cannot be collected for an image. */
-  /** Warning that the sizing information cannot be collected for an image. */
+  /** Warning that the size information for an image was nonsensical. `url` will be replaced with the url of that image. */
-  /** Warning that the sizing information cannot be collected for an image. */
+  /** Warning that the size information for an image was nonsensical. `url` will be replaced with the url of that image. */
   warningCompute: 'Invalid image sizing information {url}',
+  /** Table column header for the displayed aspect ratio of an image. */
   columnDisplayed: 'Aspect Ratio (Displayed)',
+  /** Table column header for the actual aspect ratio of an image. */
   columnActual: 'Aspect Ratio (Actual)',
 };