github-electron update (#8922)

* Update URLs to new location: https://github.com/electron/electron/blob/master/docs * Fix CrashReporter interface * Fix isMainFrame type in WebViewElement.LoadCommitEvent * Update menu-item documentation * Fix ContentTracing interface
2026-05-16 11:02:11 +08:00 · 2016-04-12 17:04:07 +02:00
parent 29db5e426c
commit 5387ccca33
2 changed files with 132 additions and 126 deletions
--- a/github-electron/github-electron-main-tests.ts
+++ b/github-electron/github-electron-main-tests.ts
@@ -340,11 +340,15 @@ win.show();
 // content-tracing
 // https://github.com/atom/electron/blob/master/docs/api/content-tracing.md

-contentTracing.startRecording('*', contentTracing.DEFAULT_OPTIONS, () => {
-	console.log('Tracing started');
+const options = {
+	categoryFilter: '*',
+	traceOptions: 'record-until-full,enable-sampling'
+}

-	setTimeout(() => {
-		contentTracing.stopRecording('', path => {
+contentTracing.startRecording(options, function() {
+	console.log('Tracing started');
+	setTimeout(function() {
+		contentTracing.stopRecording('', function(path) {
 			console.log('Tracing data recorded to ' + path);
 		});
 	}, 5000);
--- a/github-electron/github-electron.d.ts
+++ b/github-electron/github-electron.d.ts
@@ -25,7 +25,7 @@ declare namespace Electron {
 		sender: EventEmitter;
 	}

-	// https://github.com/atom/electron/blob/master/docs/api/app.md
+	// https://github.com/electron/electron/blob/master/docs/api/app.md

 	/**
 	 * The app module is responsible for controlling the application's lifecycle.
@@ -411,7 +411,7 @@ declare namespace Electron {
 		iconIndex?: number;
 	}

-	// https://github.com/atom/electron/blob/master/docs/api/auto-updater.md
+	// https://github.com/electron/electron/blob/master/docs/api/auto-updater.md

 	/**
 	 * This module provides an interface for the Squirrel auto-updater framework.
@@ -456,7 +456,7 @@ declare namespace Electron {
 		quitAndInstall(): void;
 	}

-	// https://github.com/atom/electron/blob/master/docs/api/browser-window.md
+	// https://github.com/electron/electron/blob/master/docs/api/browser-window.md

 	/**
 	 * The BrowserWindow class gives you ability to create a browser window.
@@ -1327,7 +1327,7 @@ declare namespace Electron {
 		height?: number;
 	}

-	// https://github.com/atom/electron/blob/master/docs/api/clipboard.md
+	// https://github.com/electron/electron/blob/master/docs/api/clipboard.md

 	/**
 	 * The clipboard module provides methods to perform copy and paste operations.
@@ -1397,7 +1397,7 @@ declare namespace Electron {

 	type ClipboardType = '' | 'selection';

-	// https://github.com/atom/electron/blob/master/docs/api/content-tracing.md
+	// https://github.com/electron/electron/blob/master/docs/api/content-tracing.md

 	/**
 	 * The content-tracing module is used to collect tracing data generated by the underlying Chromium content module.
@@ -1407,47 +1407,40 @@ declare namespace Electron {
 	interface ContentTracing {
 		/**
 		 * Get a set of category groups. The category groups can change as new code paths are reached.
-		 * @param callback Called once all child processes have acked to the getCategories request.
+		 *
+		 * @param callback Called once all child processes have acknowledged the getCategories request.
 		 */
 		getCategories(callback: (categoryGroups: any[]) => void): void;
 		/**
-		 * Start recording on all processes. Recording begins immediately locally, and asynchronously
+		 * Start recording on all processes. Recording begins immediately locally and asynchronously
 		 * on child processes as soon as they receive the EnableRecording request.
-		 * @param categoryFilter A filter to control what category groups should be traced.
-		 * A filter can have an optional "-" prefix to exclude category groups that contain
-		 * a matching category. Having both included and excluded category patterns in the
-		 * same list would not be supported.
-		 * @param options controls what kind of tracing is enabled, it could be a OR-ed
-		 * combination of tracing.DEFAULT_OPTIONS, tracing.ENABLE_SYSTRACE, tracing.ENABLE_SAMPLING
-		 * and tracing.RECORD_CONTINUOUSLY.
-		 * @param callback Called once all child processes have acked to the startRecording request.
+		 *
+		 * @param callback Called once all child processes have acknowledged the startRecording request.
 		 */
-		startRecording(categoryFilter: string, options: number, callback: Function): void;
+		startRecording(options: ContentTracingOptions, callback: Function): void;
 		/**
 		 * Stop recording on all processes. Child processes typically are caching trace data and
 		 * only rarely flush and send trace data back to the main process. That is because it may
 		 * be an expensive operation to send the trace data over IPC, and we would like to avoid
 		 * much runtime overhead of tracing. So, to end tracing, we must asynchronously ask all
 		 * child processes to flush any pending trace data.
+		 *
 		 * @param resultFilePath Trace data will be written into this file if it is not empty,
 		 * or into a temporary file.
-		 * @param callback Called once all child processes have acked to the stopRecording request.
+		 * @param callback Called once all child processes have acknowledged the stopRecording request.
 		 */
-		stopRecording(resultFilePath: string, callback:
-			/**
-			 * @param filePath A file that contains the traced data.
-			 */
-			(filePath: string) => void
-			): void;
+		stopRecording(resultFilePath: string, callback: (filePath: string) => void): void;
 		/**
-		 * Start monitoring on all processes. Monitoring begins immediately locally, and asynchronously
+		 * Start monitoring on all processes. Monitoring begins immediately locally and asynchronously
 		 * on child processes as soon as they receive the startMonitoring request.
+		 *
 		 * @param callback Called once all child processes have acked to the startMonitoring request.
 		 */
-		startMonitoring(categoryFilter: string, options: number, callback: Function): void;
+		startMonitoring(options: ContentTracingOptions, callback: Function): void;
 		/**
 		 * Stop monitoring on all processes.
-		 * @param callback Called once all child processes have acked to the stopMonitoring request.
+		 *
+		 * @param callback Called once all child processes have acknowledged the stopMonitoring request.
 		 */
 		stopMonitoring(callback: Function): void;
 		/**
@@ -1456,17 +1449,13 @@ declare namespace Electron {
 		 * be an expensive operation to send the trace data over IPC, and we would like to avoid much
 		 * runtime overhead of tracing. So, to end tracing, we must asynchronously ask all child
 		 * processes to flush any pending trace data.
-		 * @param callback Called once all child processes have acked to the captureMonitoringSnapshot request.
+		 *
+		 * @param callback Called once all child processes have acknowledged the captureMonitoringSnapshot request.
 		 */
-		captureMonitoringSnapshot(resultFilePath: string, callback:
-			/**
-			 * @param filePath A file that contains the traced data
-			 * @returns {}
-			 */
-			(filePath: string) => void
-			): void;
+		captureMonitoringSnapshot(resultFilePath: string, callback: (filePath: string) => void): void;
 		/**
-		 * Get the maximum across processes of trace buffer percent full state.
+		 * Get the maximum usage across processes of trace buffer as a percentage of the full state.
+		 *
 		 * @param callback Called when the TraceBufferUsage value is determined.
 		 */
 		getTraceBufferUsage(callback: Function): void;
@@ -1475,16 +1464,47 @@ declare namespace Electron {
 		 */
 		setWatchEvent(categoryName: string, eventName: string, callback: Function): void;
 		/**
-		 * Cancel the watch event. If tracing is enabled, this may race with the watch event callback.
+		 * Cancel the watch event. This may lead to a race condition with the watch event callback if tracing is enabled.
 		 */
 		cancelWatchEvent(): void;
-		DEFAULT_OPTIONS: number;
-		ENABLE_SYSTRACE: number;
-		ENABLE_SAMPLING: number;
-		RECORD_CONTINUOUSLY: number;
 	}

-	// https://github.com/atom/electron/blob/master/docs/api/crash-reporter.md
+	interface ContentTracingOptions {
+		/**
+		 * Filter to control what category groups should be traced.
+		 * A filter can have an optional - prefix to exclude category groups
+		 * that contain a matching category. Having both included and excluded
+		 * category patterns in the same list is not supported.
+		 *
+		 * Examples:
+		 *   test_MyTest*
+		 *   test_MyTest*,test_OtherStuff
+		 *   -excluded_category1,-excluded_category2
+		 */
+		categoryFilter: string;
+		/**
+		 * Controls what kind of tracing is enabled, it is a comma-delimited list.
+		 *
+		 * Possible options are:
+		 *   record-until-full
+		 *   record-continuously
+		 *   trace-to-console
+		 *   enable-sampling
+		 *   enable-systrace
+		 *
+		 * The first 3 options are trace recoding modes and hence mutually exclusive.
+		 * If more than one trace recording modes appear in the traceOptions string,
+		 * the last one takes precedence. If none of the trace recording modes are specified,
+		 * recording mode is record-until-full.
+		 *
+		 * The trace option will first be reset to the default option (record_mode set
+		 * to record-until-full, enable_sampling and enable_systrace set to false)
+		 * before options parsed from traceOptions are applied on it.
+		 */
+		traceOptions: string;
+	}
+
+	// https://github.com/electron/electron/blob/master/docs/api/crash-reporter.md

 	/**
 	 * The crash-reporter module enables sending your app's crash reports.
@@ -1492,87 +1512,56 @@ declare namespace Electron {
 	interface CrashReporter {
 		/**
 		 * You are required to call this method before using other crashReporter APIs.
+		 *
+		 * Note: On OS X, Electron uses a new crashpad client, which is different from breakpad
+		 * on Windows and Linux. To enable the crash collection feature, you are required to call
+		 * the crashReporter.start API to initialize crashpad in the main process and in each
+		 * renderer process from which you wish to collect crash reports.
 		 */
 		start(options: CrashReporterStartOptions): void;
 		/**
-		 * @returns The date and ID of the last crash report. When there was no crash report
+		 * @returns The crash report. When there was no crash report
 		 * sent or the crash reporter is not started, null will be returned.
 		 */
-		getLastCrashReport(): CrashReporterPayload;
+		getLastCrashReport(): CrashReport;
 		/**
-		 * @returns All uploaded crash reports. Each report contains the date and uploaded ID.
+		 * @returns All uploaded crash reports.
 		 */
-		getUploadedReports(): CrashReporterPayload[];
+		getUploadedReports(): CrashReport[];
 	}

 	interface CrashReporterStartOptions {
 		/**
-		* Default: Electron
-		*/
+		 * Default: Electron
+		 */
 		productName?: string;
 		companyName: string;
 		/**
-		* URL that crash reports would be sent to as POST.
-		*/
+		 * URL that crash reports would be sent to as POST.
+		 */
 		submitURL: string;
 		/**
-		* Send the crash report without user interaction.
-		* Default: true.
-		*/
+		 * Send the crash report without user interaction.
+		 * Default: true.
+		 */
 		autoSubmit?: boolean;
 		/**
-		* Default: false.
-		*/
+		 * Default: false.
+		 */
 		ignoreSystemCrashHandler?: boolean;
 		/**
-		* An object you can define which content will be send along with the report.
-		* Only string properties are send correctly.
-		* Nested objects are not supported.
-		*/
+		 * An object you can define that will be sent along with the report.
+		 * Only string properties are sent correctly, nested objects are not supported.
+		 */
 		extra?: {[prop: string]: string};
 	}

-	interface CrashReporterPayload extends Object {
-		/**
-		* E.g., "electron-crash-service".
-		*/
-		rept: string;
-		/**
-		* The version of Electron.
-		*/
-		ver: string;
-		/**
-		* E.g., "win32".
-		*/
-		platform: string;
-		/**
-		* E.g., "renderer".
-		*/
-		process_type: string;
-		ptime: number;
-		/**
-		* The version in package.json.
-		*/
-		_version: string;
-		/**
-		* The product name in the crashReporter options object.
-		*/
-		_productName: string;
-		/**
-		* Name of the underlying product. In this case, Electron.
-		*/
-		prod: string;
-		/**
-		* The company name in the crashReporter options object.
-		*/
-		_companyName: string;
-		/**
-		* The crashreporter as a file.
-		*/
-		upload_file_minidump: File;
+	interface CrashReport {
+		id: string;
+		date: Date;
 	}

-	// https://github.com/atom/electron/blob/master/docs/api/desktop-capturer.md
+	// https://github.com/electron/electron/blob/master/docs/api/desktop-capturer.md

 	/**
 	 * The desktopCapturer module can be used to get available sources
@@ -1618,7 +1607,7 @@ declare namespace Electron {
 		thumbnail: NativeImage;
 	}

-	// https://github.com/atom/electron/blob/master/docs/api/dialog.md
+	// https://github.com/electron/electron/blob/master/docs/api/dialog.md

 	/**
 	 * The dialog module provides APIs to show native system dialogs, such as opening files or alerting,
@@ -1752,7 +1741,7 @@ declare namespace Electron {
 		noLink?: boolean;
 	}

-	// https://github.com/atom/electron/blob/master/docs/api/download-item.md
+	// https://github.com/electron/electron/blob/master/docs/api/download-item.md

 	/**
 	 * DownloadItem represents a download item in Electron.
@@ -1820,7 +1809,7 @@ declare namespace Electron {
 		getContentDisposition(): string;
 	}

-	// https://github.com/atom/electron/blob/master/docs/api/global-shortcut.md
+	// https://github.com/electron/electron/blob/master/docs/api/global-shortcut.md

 	/**
 	 * The globalShortcut module can register/unregister a global keyboard shortcut
@@ -1854,7 +1843,7 @@ declare namespace Electron {
 		unregisterAll(): void;
 	}

-	// https://github.com/atom/electron/blob/master/docs/api/ipc-main.md
+	// https://github.com/electron/electron/blob/master/docs/api/ipc-main.md

 	/**
 	 * The ipcMain module handles asynchronous and synchronous messages
@@ -1883,7 +1872,7 @@ declare namespace Electron {
 		sender: WebContents;
 	}

-	// https://github.com/atom/electron/blob/master/docs/api/ipc-renderer.md
+	// https://github.com/electron/electron/blob/master/docs/api/ipc-renderer.md

 	/**
 	 * The ipcRenderer module provides a few methods so you can send synchronous
@@ -1926,7 +1915,8 @@ declare namespace Electron {
 		sender: IpcRenderer;
 	}

-	// https://github.com/atom/electron/blob/master/docs/api/menu-item.md
+	// https://github.com/electron/electron/blob/master/docs/api/menu-item.md
+	// https://github.com/electron/electron/blob/master/docs/api/accelerator.md

 	/**
 	 * The MenuItem allows you to add items to an application or context menu.
@@ -1986,14 +1976,17 @@ declare namespace Electron {
 		 * multiple modifiers and key codes, combined by the + character.
 		 *
 		 * Examples:
-		 *   Command+A
-		 *   Ctrl+Shift+Z
+		 *   CommandOrControl+A
+		 *   CommandOrControl+Shift+Z
 		 *
 		 * Platform notice:
 		 *   On Linux and Windows, the Command key would not have any effect,
 		 *   you can use CommandOrControl which represents Command on OS X and Control on
 		 *   Linux and Windows to define some accelerators.
 		 *
+		 *   Use Alt instead of Option. The Option key only exists on OS X, whereas
+		 *   the Alt key is available on all platforms.
+		 *
 		 *   The Super key is mapped to the Windows key on Windows and Linux and Cmd on OS X.
 		 *
 		 * Available modifiers:
@@ -2031,8 +2024,17 @@ declare namespace Electron {
 		 * or NativeImage instances. When passing null, an empty image will be used.
 		 */
 		icon?: NativeImage|string;
+		/**
+		 * If false, the menu item will be greyed out and unclickable.
+		 */
 		enabled?: boolean;
+		/**
+		 * If false, the menu item will be entirely hidden.
+		 */
 		visible?: boolean;
+		/**
+		 * Should only be specified for 'checkbox' or 'radio' type menu items.
+		 */
 		checked?: boolean;
 		/**
 		 * Should be specified for submenu type menu item, when it's specified the
@@ -2055,7 +2057,7 @@ declare namespace Electron {
 		role?: MenuItemRole | MenuItemRoleMac;
 	}

-	// https://github.com/atom/electron/blob/master/docs/api/menu.md
+	// https://github.com/electron/electron/blob/master/docs/api/menu.md

 	/**
 	 * The Menu class is used to create native menus that can be used as application
@@ -2110,7 +2112,7 @@ declare namespace Electron {
 		items: MenuItem[];
 	}

-	// https://github.com/atom/electron/blob/master/docs/api/native-image.md
+	// https://github.com/electron/electron/blob/master/docs/api/native-image.md

 	/**
 	 * This class is used to represent an image.
@@ -2169,7 +2171,7 @@ declare namespace Electron {
 		isTemplateImage(): boolean;
 	}

-	// https://github.com/atom/electron/blob/master/docs/api/power-monitor.md
+	// https://github.com/electron/electron/blob/master/docs/api/power-monitor.md

 	/**
 	 * The power-monitor module is used to monitor power state changes.
@@ -2195,7 +2197,7 @@ declare namespace Electron {
 		on(event: string, listener: Function): this;
 	}

-	// https://github.com/atom/electron/blob/master/docs/api/power-save-blocker.md
+	// https://github.com/electron/electron/blob/master/docs/api/power-save-blocker.md

 	/**
 	 * The powerSaveBlocker module is used to block the system from entering
@@ -2220,7 +2222,7 @@ declare namespace Electron {
 		isStarted(id: number): boolean;
 	}

-	// https://github.com/atom/electron/blob/master/docs/api/protocol.md
+	// https://github.com/electron/electron/blob/master/docs/api/protocol.md

 	/**
 	 * The protocol module can register a custom protocol or intercept an existing protocol.
@@ -2335,7 +2337,7 @@ declare namespace Electron {
 		}): void;
 	}

-	// https://github.com/atom/electron/blob/master/docs/api/remote.md
+	// https://github.com/electron/electron/blob/master/docs/api/remote.md

 	/**
 	 * The remote module provides a simple way to do inter-process communication (IPC)
@@ -2365,7 +2367,7 @@ declare namespace Electron {
 		process: NodeJS.Process;
 	}

-	// https://github.com/atom/electron/blob/master/docs/api/screen.md
+	// https://github.com/electron/electron/blob/master/docs/api/screen.md

 	/**
 	 * The Display object represents a physical display connected to the system.
@@ -2450,7 +2452,7 @@ declare namespace Electron {
 		getDisplayMatching(rect: Bounds): Display;
 	}

-	// https://github.com/atom/electron/blob/master/docs/api/session.md
+	// https://github.com/electron/electron/blob/master/docs/api/session.md

 	/**
 	 * The session module can be used to create new Session objects.
@@ -2695,7 +2697,7 @@ declare namespace Electron {
 		remove(url: string, name: string, callback: (error: Error) => void): void;
 	}

-	// https://github.com/atom/electron/blob/master/docs/api/shell.md
+	// https://github.com/electron/electron/blob/master/docs/api/shell.md

 	/**
 	 * The shell module provides functions related to desktop integration.
@@ -2732,7 +2734,7 @@ declare namespace Electron {
 		beep(): void;
 	}

-	// https://github.com/atom/electron/blob/master/docs/api/tray.md
+	// https://github.com/electron/electron/blob/master/docs/api/tray.md

 	/**
 	 * A Tray represents an icon in an operating system's notification area.
@@ -2853,7 +2855,7 @@ declare namespace Electron {
 		metaKey: boolean;
 	}

-	// https://github.com/atom/electron/blob/master/docs/api/web-contents.md
+	// https://github.com/electron/electron/blob/master/docs/api/web-contents.md

 	/**
 	 * A WebContents is responsible for rendering and controlling a web page.
@@ -3564,7 +3566,7 @@ declare namespace Electron {
 		on(event: string, listener: Function): this;
 	}

-	// https://github.com/atom/electron/blob/master/docs/api/web-frame.md
+	// https://github.com/electron/electron/blob/master/docs/api/web-frame.md

 	/**
 	 * The web-frame module allows you to customize the rendering of the current web page.
@@ -3630,7 +3632,7 @@ declare namespace Electron {
 		executeJavaScript(code: string, userGesture?: boolean, callback?: (result: any) => void): void;
 	}

-	// https://github.com/atom/electron/blob/master/docs/api/web-view-tag.md
+	// https://github.com/electron/electron/blob/master/docs/api/web-view-tag.md

 	/**
 	 * Use the webview tag to embed 'guest' content (such as web pages) in your Electron app.
@@ -4056,7 +4058,7 @@ declare namespace Electron {

 		interface LoadCommitEvent extends Event  {
 			url: string;
-			isMainFrame: string;
+			isMainFrame: boolean;
 		}

 		interface DidFailLoadEvent extends Event  {
@@ -4163,7 +4165,7 @@ declare namespace Electron {
 		postMessage(message: string, targetOrigin: string): void;
 	}

-	// https://github.com/atom/electron/blob/master/docs/api/synopsis.md
+	// https://github.com/electron/electron/blob/master/docs/api/synopsis.md

 	interface CommonElectron {
 		clipboard: Electron.Clipboard;
@@ -4205,7 +4207,7 @@ interface Document {
 	createElement(tagName: 'webview'): Electron.WebViewElement;
 }

-// https://github.com/atom/electron/blob/master/docs/api/window-open.md
+// https://github.com/electron/electron/blob/master/docs/api/window-open.md

 interface Window {
 	/**
@@ -4214,7 +4216,7 @@ interface Window {
 	open(url: string, frameName?: string, features?: string): Electron.BrowserWindowProxy;
 }

-// https://github.com/atom/electron/blob/master/docs/api/file-object.md
+// https://github.com/electron/electron/blob/master/docs/api/file-object.md

 interface File {
 	/**