From f55f5abbb65bcef040fc92f83cfa54bc70a66483 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fredrik=20H=C3=B8is=C3=A6ther=20Rasch?=
 <fredrik.rasch@gmail.com>
Date: Sun, 27 Sep 2015 15:47:58 +0200
Subject: [PATCH] Added/Updated webNavigation /w docs

---
 chrome/chrome.d.ts | 212 +++++++++++++++++++++++++++------------------
 1 file changed, 130 insertions(+), 82 deletions(-)

diff --git a/chrome/chrome.d.ts b/chrome/chrome.d.ts
index f22ce4e2f0..f0af67d70d 100755
--- a/chrome/chrome.d.ts
+++ b/chrome/chrome.d.ts
@@ -7468,130 +7468,178 @@ declare module chrome.wallpaper {
 ////////////////////
 // Web Navigation
 ////////////////////
+/**
+ * Use the chrome.webNavigation API to receive notifications about the status of navigation requests in-flight. 
+ * Permissions:  "webNavigation"   
+ * @since Chrome 16.
+ */
 declare module chrome.webNavigation {
 	interface GetFrameDetails {
+		/**
+		 * The ID of the process runs the renderer for this tab. 
+		 * @since Chrome 22.
+		 */
 		processId: number;
+		/** The ID of the tab in which the frame is. */
 		tabId: number;
+		/** The ID of the frame in the given tab. */
 		frameId: number;
 	}
 
 	interface GetFrameResultDetails {
+		/** The URL currently associated with this frame, if the frame identified by the frameId existed at one point in the given tab. The fact that an URL is associated with a given frameId does not imply that the corresponding frame still exists. */
 		url: string;
+		/** True if the last navigation in this frame was interrupted by an error, i.e. the onErrorOccurred event fired. */
 		errorOccurred: boolean;
+		/** ID of frame that wraps the frame. Set to -1 of no parent frame exists. */
 		parentFrameId: number;
 	}
 
 	interface GetAllFrameDetails {
+		/** The ID of the tab. */
 		tabId: number;
 	}
 
 	interface GetAllFrameResultDetails extends GetFrameResultDetails {
+		/** The ID of the process runs the renderer for this tab. */
 		processId: number;
+		/** The ID of the frame. 0 indicates that this is the main frame; a positive value indicates the ID of a subframe. */
 		frameId: number;
 	}
-
-	interface CallbackBasicDetails {
+	
+	interface WebNavigationCallbackDetails {
+		/** The ID of the tab in which the navigation is about to occur. */
 		tabId: number;
+		/** The time when the browser was about to start the navigation, in milliseconds since the epoch. */
 		timeStamp: number;
 	}
 
-	interface CallbackDetails extends CallbackBasicDetails {
-		processId: number;
+	interface WebNavigationUrlCallbackDetails extends WebNavigationCallbackDetails {
 		url: string;
-		frameId: number;
 	}
-
-	interface CallbackTransitionDetails extends CallbackDetails {
-		transitionType: string;
-		transitionQualifiers: string[];
-	}
-
-	interface ReferenceFragmentUpdatedDetails extends CallbackTransitionDetails {
-	}
-
-	interface CompletedDetails extends CallbackDetails {
-	}
-
-	interface HistoryStateUpdatedDetails extends CallbackTransitionDetails {
-	}
-
-	interface CreatedNavigationTargetDetails extends CallbackBasicDetails {
-		url: string;
-		sourceTabId: number;
-		sourceProcessId: number;
-		sourceFrameId: number;
-	}
-
-	interface TabReplacedDetails extends CallbackBasicDetails {
+	
+	interface WebNavigationReplacementCallbackDetails extends WebNavigationCallbackDetails {
+		/** The ID of the tab that was replaced. */
 		replacedTabId: number;
 	}
-
-	interface BeforeNavigateDetails extends CallbackDetails {
-		parentFrameId: number;
+	
+	interface WebNavigationFramedCallbackDetails extends WebNavigationUrlCallbackDetails {
+		/** 0 indicates the navigation happens in the tab content window; a positive value indicates navigation in a subframe. Frame IDs are unique for a given tab and process. */
+		frameId: number;
+		/**
+		 * The ID of the process runs the renderer for this tab. 
+		 * @since Chrome 22.
+		 */
+		processId: number;
 	}
-
-	interface CommittedDetails extends CallbackTransitionDetails {
-	}
-
-	interface DomContentLoadedDetails extends CallbackDetails {
-	}
-
-	interface ErrorOccurredDetails extends CallbackDetails {
+	
+	interface WebNavigationFramedErrorCallbackDetails extends WebNavigationFramedCallbackDetails {
+		/** The error description. */
 		error: string;
 	}
-
-	interface WebNavigationEventFilters {
+	
+	interface WebNavigationSourceCallbackDetails extends WebNavigationUrlCallbackDetails {
+		/** The ID of the tab in which the navigation is triggered. */
+		sourceTabId: number;
+		/**
+		 * The ID of the process runs the renderer for the source tab. 
+		 * @since Chrome 22.
+		 */
+		sourceProcessId: number;
+		/** The ID of the frame with sourceTabId in which the navigation is triggered. 0 indicates the main frame. */
+		sourceFrameId: number;
+	}
+	
+	interface WebNavigationParentedCallbackDetails extends WebNavigationFramedCallbackDetails {
+		/**
+		 * ID of frame that wraps the frame. Set to -1 of no parent frame exists. 
+		 * @since Chrome 24.
+		 */
+		parentFrameId: number;
+	}
+	
+	interface WebNavigationTransitionCallbackDetails extends WebNavigationFramedCallbackDetails {
+		/**
+		 * Cause of the navigation. 
+		 * One of: "link", "typed", "auto_bookmark", "auto_subframe", "manual_subframe", "generated", "start_page", "form_submit", "reload", "keyword", or "keyword_generated" 
+		 */
+		transitionType: string;
+		/**
+		 * A list of transition qualifiers. 
+		 * Each element one of: "client_redirect", "server_redirect", "forward_back", or "from_address_bar" 
+		 */
+		transitionQualifiers: string[];
+	}
+	
+	interface WebNavigationEvent extends chrome.events.Event {
+		/** Conditions that the URL being navigated to must satisfy. The 'schemes' and 'ports' fields of UrlFilter are ignored for this event. */
 		url: chrome.events.UrlFilter[];
+		addListener(callback: (details: WebNavigationCallbackDetails) => void): void;		
+	}
+	
+	interface WebNavigationFramedEvent extends WebNavigationEvent {
+		addListener(callback: (details: WebNavigationFramedCallbackDetails) => void): void;		
+	}
+	
+	interface WebNavigationFramedErrorEvent extends WebNavigationFramedEvent {
+		addListener(callback: (details: WebNavigationFramedErrorCallbackDetails) => void): void;		
+	}
+	
+	interface WebNavigationSourceEvent extends WebNavigationEvent {
+		addListener(callback: (details: WebNavigationSourceCallbackDetails) => void): void;
 	}
 
-	interface WebNavigationReferenceFragmentUpdatedEvent extends chrome.events.Event {
-		addListener(callback: (details: ReferenceFragmentUpdatedDetails) => void, filters?: WebNavigationEventFilters): void;
+	interface WebNavigationParentedEvent extends WebNavigationEvent {
+		addListener(callback: (details: WebNavigationParentedCallbackDetails) => void): void;
 	}
 
-	interface WebNavigationCompletedEvent extends chrome.events.Event {
-		addListener(callback: (details: CompletedDetails) => void, filters?: WebNavigationEventFilters): void;
-	}
-
-	interface WebNavigationHistoryStateUpdatedEvent extends chrome.events.Event {
-		addListener(callback: (details: HistoryStateUpdatedDetails) => void, filters?: WebNavigationEventFilters): void;
-	}
-
-	interface WebNavigationCreatedNavigationTargetEvent extends chrome.events.Event {
-		addListener(callback: (details: CreatedNavigationTargetDetails) => void, filters?: WebNavigationEventFilters): void;
-	}
-
-	interface WebNavigationTabReplacedEvent extends chrome.events.Event {
-		addListener(callback: (details: TabReplacedDetails) => void): void;
-	}
-
-	interface WebNavigationBeforeNavigateEvent extends chrome.events.Event {
-		addListener(callback: (details: BeforeNavigateDetails) => void, filters?: WebNavigationEventFilters): void;
-	}
-
-	interface WebNavigationCommittedEvent extends chrome.events.Event {
-		addListener(callback: (details: CommittedDetails) => void, filters?: WebNavigationEventFilters): void;
-	}
-
-	interface WebNavigationDomContentLoadedEvent extends chrome.events.Event {
-		addListener(callback: (details: DomContentLoadedDetails) => void, filters?: WebNavigationEventFilters): void;
-	}
-
-	interface WebNavigationErrorOccurredEvent extends chrome.events.Event {
-		addListener(callback: (details: ErrorOccurredDetails) => void, filters?: WebNavigationEventFilters): void;
+	interface WebNavigationTransitionalEvent extends WebNavigationEvent {
+		addListener(callback: (details: WebNavigationTransitionCallbackDetails) => void): void;
+	}
+	
+	interface WebNavigationReplacementEvent extends WebNavigationEvent {
+		addListener(callback: (details: WebNavigationReplacementCallbackDetails) => void): void;
 	}
 
+	/**
+	 * Retrieves information about the given frame. A frame refers to an <iframe> or a <frame> of a web page and is identified by a tab ID and a frame ID. 
+	 * @param details Information about the frame to retrieve information about. 
+	 * @param callback
+	 * Optional parameter details: Information about the requested frame, null if the specified frame ID and/or tab ID are invalid. 
+	 */
 	export function getFrame(details: GetFrameDetails, callback: (details?: GetFrameResultDetails) => void): void;
+	/**
+	 * Retrieves information about all frames of a given tab. 
+	 * @param details Information about the tab to retrieve all frames from.
+	 * @param callback
+	 * Optional parameter details: A list of frames in the given tab, null if the specified tab ID is invalid.  
+	 */
 	export function getAllFrames(details: GetAllFrameDetails, callback: (details?: GetAllFrameResultDetails[]) => void): void;
 
-	var onReferenceFragmentUpdated: WebNavigationReferenceFragmentUpdatedEvent;
-	var onCompleted: WebNavigationCompletedEvent;
-	var onHistoryStateUpdated: WebNavigationHistoryStateUpdatedEvent;
-	var onCreatedNavigationTarget: WebNavigationCreatedNavigationTargetEvent;
-	var onTabReplaced: WebNavigationTabReplacedEvent;
-	var onBeforeNavigate: WebNavigationBeforeNavigateEvent;
-	var onCommitted: WebNavigationCommittedEvent;
-	var onDOMContentLoaded: WebNavigationDomContentLoadedEvent;
-	var onErrorOccurred: WebNavigationErrorOccurredEvent;
+	/** Fired when the reference fragment of a frame was updated. All future events for that frame will use the updated URL. */    
+	var onReferenceFragmentUpdated: WebNavigationTransitionalEvent;
+	/** Fired when a document, including the resources it refers to, is completely loaded and initialized. */
+	var onCompleted: WebNavigationFramedEvent;
+	/**
+	 * Fired when the frame's history was updated to a new URL. All future events for that frame will use the updated URL. 
+	 * @since Chrome 22.
+	 */
+	var onHistoryStateUpdated: WebNavigationTransitionalEvent;
+	/** Fired when a new window, or a new tab in an existing window, is created to host a navigation. */
+	var onCreatedNavigationTarget: WebNavigationSourceEvent;
+	/**
+	 * Fired when the contents of the tab is replaced by a different (usually previously pre-rendered) tab. 
+	 * @since Chrome 22.
+	 */
+	var onTabReplaced: WebNavigationReplacementEvent;
+	/** Fired when a navigation is about to occur. */
+	var onBeforeNavigate: WebNavigationParentedEvent;
+	/** Fired when a navigation is committed. The document (and the resources it refers to, such as images and subframes) might still be downloading, but at least part of the document has been received from the server and the browser has decided to switch to the new document. */
+	var onCommitted: WebNavigationTransitionalEvent;
+	/** Fired when the page's DOM is fully constructed, but the referenced resources may not finish loading. */
+	var onDOMContentLoaded: WebNavigationFramedEvent;
+	/** Fired when an error occurs and the navigation is aborted. This can happen if either a network error occurred, or the user aborted the navigation. */
+	var onErrorOccurred: WebNavigationFramedErrorEvent;
 }
 
 ////////////////////