Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

misc: use jsdoc-style comments on Flags properties #7359

Merged
merged 1 commit into from
Mar 4, 2019
Merged

misc: use jsdoc-style comments on Flags properties #7359

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 44 additions & 36 deletions types/externs.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,19 +59,19 @@ declare global {

/** Simulation settings that control the amount of network & cpu throttling in the run. */
interface ThrottlingSettings {
// The round trip time in milliseconds
/** The round trip time in milliseconds. */
rttMs?: number;
// The network throughput in kilobytes per second
/** The network throughput in kilobytes per second. */
throughputKbps?: number;
// devtools settings
// The network request latency in milliseconds
/** The network request latency in milliseconds. */
requestLatencyMs?: number;
// The network download throughput in kilobytes per second
/** The network download throughput in kilobytes per second. */
downloadThroughputKbps?: number;
// The network upload throughput in kilobytes per second
/** The network upload throughput in kilobytes per second. */
uploadThroughputKbps?: number;
// used by both
// The amount of slowdown applied to the cpu (1/<cpuSlowdownMultiplier>)
/** The amount of slowdown applied to the cpu (1/<cpuSlowdownMultiplier>). */
cpuSlowdownMultiplier?: number
}

Expand All @@ -89,39 +89,39 @@ declare global {
* interface and the Config's `settings` object.
*/
interface SharedFlagsSettings {
// The output types (json, html, ...)
/** The type(s) of report output to be produced. */
output?: OutputMode|OutputMode[];
// The locale setting
/** The locale to use for the output. */
locale?: Locale;
// The maximum amount of time to wait for a page to load in ms
/** The maximum amount of time to wait for a page to load, in ms. */
maxWaitForLoad?: number;
// List of URL patterns to block
/** List of URL patterns to block. */
blockedUrlPatterns?: string[] | null;
// Comma-delimited list of trace categories to include
/** Comma-delimited list of trace categories to include. */
additionalTraceCategories?: string | null;
// Flag indicating the run should only audit
/** Flag indicating the run should only audit. */
auditMode?: boolean | string;
// Flag indicating the run should only gather
/** Flag indicating the run should only gather. */
gatherMode?: boolean | string;
// Flag indicating that the browser storage should not be reset for the audit
/** Flag indicating that the browser storage should not be reset for the audit. */
disableStorageReset?: boolean;
// Flag indicating that there shouldn't be any emulation during the run
/** Flag indicating that there shouldn't be any emulation during the run. */
disableDeviceEmulation?: boolean;
// The form factor the emulation should use
/** The form factor the emulation should use. */
emulatedFormFactor?: 'mobile'|'desktop'|'none';
// The method used to throttle the network
/** The method used to throttle the network. */
throttlingMethod?: 'devtools'|'simulate'|'provided';
// The throttling config settings
/** The throttling config settings. */
throttling?: ThrottlingSettings;
// List of audits that the run should conduct
/** If present, the run should only conduct this list of audits. */
onlyAudits?: string[] | null;
// List of categories of audits the run should conduct
/** If present, the run should only conduct this list of categories. */
onlyCategories?: string[] | null;
// List of audits that the run should skip
/** If present, the run should skip this list of audits. */
skipAudits?: string[] | null;
// List of extra HTTP Headers to include
/** List of extra HTTP Headers to include. */
extraHeaders?: Crdp.Network.Headers | null; // See extraHeaders TODO in bin.js
// Precomputed lantern estimates to use instead of observed analysis
/** Precomputed lantern estimates to use instead of observed analysis. */
precomputedLanternData?: PrecomputedLanternData | null;
}

Expand All @@ -130,9 +130,13 @@ declare global {
* Lighthouse module but will not end up in the Config settings.
*/
export interface Flags extends SharedFlagsSettings {
/** The port to use for the debugging protocol, if manually connecting. */
port?: number;
/** The hostname to use for the debugging protocol, if manually connecting. */
hostname?: string;
/** The level of logging to enable. */
logLevel?: 'silent'|'error'|'info'|'verbose';
/** The path to the config JSON. */
configPath?: string;
}

Expand All @@ -143,31 +147,35 @@ declare global {
export interface CliFlags extends Flags {
_: string[];
chromeFlags: string;
// Output path for the generated assets
/** Output path for the generated results. */
outputPath: string;
// Flag to save the trace contents and screenshots to disk
/** Flag to save the trace contents and screenshots to disk. */
saveAssets: boolean;
// Flag to open the report immediately
/** Flag to open the report immediately. */
view: boolean;
// Enables error reporting
/** Flag to enable error reporting. */
enableErrorReporting?: boolean;
// Flag to print out a list of all audits + categories
/** Flag to print a list of all audits + categories. */
listAllAudits: boolean;
// Flag to print out a list of all required trace categories
/** Flag to print a list of all required trace categories. */
listTraceCategories: boolean;
// A preset audit of selected audit categories to run
/** A preset audit of selected audit categories to run. */
preset?: 'full'|'mixed-content'|'perf';
/** A flag to enable logLevel 'verbose'. */
verbose: boolean;
/** A flag to enable logLevel 'silent'. */
quiet: boolean;
// following are given defaults in cli-flags, so are not optional like in Flags or SharedFlagsSettings
output: OutputMode[];
port: number;
hostname: string;
/** A flag to print the normalized config for the given config and options, then exit. */
printConfig: boolean;
// Path to the file where precomputed lantern data should be read from.
/** Path to the file where precomputed lantern data should be read from. */
precomputedLanternDataPath?: string;
// Path to the file where precomputed lantern data should be written to.
/** Path to the file where precomputed lantern data should be written to. */
lanternDataOutputPath?: string;

// The following are given defaults in cli-flags, so are not optional like in Flags or SharedFlagsSettings.
Copy link
Member

@exterkamp exterkamp Mar 2, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this also be /** */?

Or is it just // b/c it is a comment instead of an annotation for a single field?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or is it just // b/c it is a comment instead of an annotation for a single field?

exactly. It's an explanation for why the properties below that point are different (those three properties also have doc strings from their base definitions in SharedFlagsSettings and Flags)

output: OutputMode[];
port: number;
hostname: string;
}

export interface RunnerResult {
Expand Down