[Fuchsia] Update FIDL definitions to use flow-through comments.

Bug: 922839
Change-Id: Ifd5e64178533aead481322038164bd4229c40102
Reviewed-on: https://chromium-review.googlesource.com/c/1423899
Commit-Queue: Wez <wez@chromium.org>
Reviewed-by: Sergey Ulanov <sergeyu@chromium.org>
Cr-Commit-Position: refs/heads/master@{#625248}

fuchsia/fidl/cast/application_config.fidl

@@ -4,21 +4,21 @@
 
 library chromium.cast;
 
-// Describes the configuration under which a Cast application should run.
+/// Describes the configuration under which a Cast application should run.
 struct ApplicationConfig {
-  // Cast application Id.
+  /// Cast application Id.
   string id;
 
-  // Name to display to the user when referring to this application.
+  /// Name to display to the user when referring to this application.
   string display_name;
 
-  // Standard web URL from which to load the application.
+  /// Standard web URL from which to load the application.
   string web_url;
 };
 
-// Service interface for working with application configurations.
+/// Service interface for working with application configurations.
 [Discoverable]
 interface ApplicationConfigManager {
-  // Returns the ApplicationConfig for the specified application Id.
+  /// Returns the ApplicationConfig for the specified application Id.
   1: GetConfig(string id) -> (ApplicationConfig? config);
 };

fuchsia/fidl/cast/cast_channel.fidl

@@ -8,10 +8,10 @@ using chromium.web;
 
 [Discoverable]
 interface CastChannel {
-  // Handles Cast Channel open calls from the webpage.
-  // The new Cast Channel's message port is returned asynchronously once
-  // opened by the webpage. The port is disconnected when the peer's Cast
-  // Channel is closed.
+  /// Handles Cast Channel open calls from the webpage.
+  /// The new Cast Channel's message port is returned asynchronously once
+  /// opened by the webpage. The port is disconnected when the peer's Cast
+  /// Channel is closed.
   1: Connect() -> (chromium.web.MessagePort channel);
 };
 

fuchsia/fidl/web/context.fidl

@@ -4,11 +4,11 @@
 
 library chromium.web;
 
-// Manages browsing state (e.g. LocalStorage, cookies, etc) associated with
-// a set of Frames.
+/// Manages browsing state (e.g. LocalStorage, cookies, etc) associated with
+/// a set of Frames.
 interface Context {
-  // Creates a new frame under this Context.
-  //
-  // |frame|: An interface request that will be bound to the created Frame.
+  /// Creates a new frame under this Context.
+  ///
+  /// |frame|: An interface request that will be bound to the created Frame.
   CreateFrame(request<Frame> frame);
 };

fuchsia/fidl/web/context_provider.fidl

@@ -4,26 +4,26 @@
 
 library chromium.web;
 
-// The top-level service interface which allows for the creation of
-// Context resources.
+/// The top-level service interface which allows for the creation of
+/// Context resources.
 [Discoverable]
 interface ContextProvider {
-  // Creates a new browser Context whose state is wholly independent and
-  // isolated from other Contexts.
-  //
-  // context: An interface request which will receive a bound Context
-  //          service.
+  /// Creates a new browser Context whose state is wholly independent and
+  /// isolated from other Contexts.
+  ///
+  /// context: An interface request which will receive a bound Context
+  ///          service.
   Create(CreateContextParams params, request<Context> context);
 };
 
 struct CreateContextParams {
-  // Service directory to be used by the context.
+  /// Service directory to be used by the context.
   // TODO(https://crbug.com/870057): Document required and optional services
   // that Context needs.
   handle<channel> service_directory;
 
-  // Handle to the directory that will contain the Context's
-  // persistent data. If it is left unset, then the created Context will be
-  // stateless, with all of its data discarded upon Context destruction.
+  /// Handle to the directory that will contain the Context's
+  /// persistent data. If it is left unset, then the created Context will be
+  /// stateless, with all of its data discarded upon Context destruction.
   handle<channel>? data_directory;
 };

fuchsia/fidl/web/frame.fidl

@@ -9,24 +9,31 @@ using fuchsia.sys;
 using fuchsia.ui.viewsv1token;
 
 enum ExecuteMode {
-  IMMEDIATE_ONCE = 1;  // Will evaluate the script immediately.
-  ON_PAGE_LOAD = 2;    // Will evaluate the script on all subsequent page loads.
+  /// Evaluate the script immediately.
+  IMMEDIATE_ONCE = 1;
+  /// Evaluate the script on all subsequent page loads.
+  ON_PAGE_LOAD = 2;
 };
 
 enum LogLevel : int32 {
-  NONE = 100;  // No logging.
-  DEBUG = -1;  // Outputs messages from console.debug().
-  INFO = 0;    // Outputs messages from console.log().
-  WARN = 1;    // Outputs messages from console.warn().
-  ERROR = 2;   // Outputs messages from console.error().
+  /// No logging.
+  NONE = 100;
+  /// Outputs messages from console.debug().
+  DEBUG = -1;
+  /// Outputs messages from console.log().
+  INFO = 0;
+  /// Outputs messages from console.warn().
+  WARN = 1;
+  /// Outputs messages from console.error().
+  ERROR = 2;
 };
 
 interface Frame {
-  // Creates a new view using the specified |view_token|. Caller should pass the
-  // other end of the token to CreateViewHolderCmd() to attach the new view to a
-  // the view tree.
-  //
-  // |view_token|: Token for the new view.
+  /// Creates a new view using the specified |view_token|. Caller should pass
+  /// the other end of the token to CreateViewHolderCmd() to attach the new view
+  /// to a the view tree.
+  ///
+  /// |view_token|: Token for the new view.
   CreateView2(handle<eventpair> view_token,
                  request<fuchsia.sys.ServiceProvider>? incoming_services,
                  fuchsia.sys.ServiceProvider? outgoing_services);
@@ -37,70 +44,70 @@ interface Frame {
   CreateView(request<fuchsia.ui.viewsv1token.ViewOwner> view_owner,
                 request<fuchsia.sys.ServiceProvider>? services);
 
-  // Returns an interface through which the frame may be navigated to
-  // a desired URL, reloaded, etc.
-  //
-  // |view_provider|: An interface request for the Frame's
-  // NavigationController.
+  /// Returns an interface through which the frame may be navigated to
+  /// a desired URL, reloaded, etc.
+  ///
+  /// |view_provider|: An interface request for the Frame's
+  /// NavigationController.
   GetNavigationController(request<NavigationController> controller);
 
-  // Executes |script| in the frame if the frame's URL has an origin which
-  // matches entries in |origins|.
-  // At least one |origins| entry must be specified.
-  // If a wildcard "*" is specified in |origins|, then the script will be
-  // evaluated for all documents.
-  // If |mode| is NOW, then the script is evaluated immediately.
-  // If |mode| is ON_PAGE_LOAD, then the script is evaluated on every future
-  // document load prior to the page's script's execution.
-  //
-  // Multiple scripts can be registered by calling ExecuteJavascript()
-  // repeatedly.
-  //
-  // Note that scripts share the same execution context as the document,
-  // meaning that document may modify variables, classes, or objects set by the
-  // script in arbitrary or unpredictable ways.
+  /// Executes |script| in the frame if the frame's URL has an origin which
+  /// matches entries in |origins|.
+  /// At least one |origins| entry must be specified.
+  /// If a wildcard "*" is specified in |origins|, then the script will be
+  /// evaluated for all documents.
+  /// If |mode| is NOW, then the script is evaluated immediately.
+  /// If |mode| is ON_PAGE_LOAD, then the script is evaluated on every future
+  /// document load prior to the page's script's execution.
+  ///
+  /// Multiple scripts can be registered by calling ExecuteJavascript()
+  /// repeatedly.
+  ///
+  /// Note that scripts share the same execution context as the document,
+  /// meaning that document may modify variables, classes, or objects set by the
+  /// script in arbitrary or unpredictable ways.
   // TODO(crbug.com/900391): Investigate if we can run the scripts in isolated
   // JS worlds.
-  //
-  // Returns |true| if the script was executed, |false| if the script was
-  // rejected due to injection being blocked by the parent Context, or because
-  // the script's text encoding was invalid.
+  ///
+  /// Returns |true| if the script was executed, |false| if the script was
+  /// rejected due to injection being blocked by the parent Context, or because
+  /// the script's text encoding was invalid.
   ExecuteJavaScript(
      vector<string> origins, fuchsia.mem.Buffer script, ExecuteMode mode) ->
      (bool success);
 
-  // Posts a message to the frame's onMessage handler.
-  //
-  // |targetOrigin| restricts message delivery to the specified origin.
-  // If |targetOrigin| is "*", then the message will be sent to the document
-  // regardless of its origin.
-  // See html.spec.whatwg.org/multipage/web-messaging.html sect. 9.4.3
-  // for more details on how the target origin policy is applied.
-  //
-  // Returns |false| if |message| is invalid or |targetOrigin| is missing.
+  /// Posts a message to the frame's onMessage handler.
+  ///
+  /// |targetOrigin| restricts message delivery to the specified origin.
+  /// If |targetOrigin| is "*", then the message will be sent to the document
+  /// regardless of its origin.
+  /// See html.spec.whatwg.org/multipage/web-messaging.html sect. 9.4.3
+  /// for more details on how the target origin policy is applied.
+  ///
+  /// Returns |false| if |message| is invalid or |targetOrigin| is missing.
   PostMessage(WebMessage message, string targetOrigin) -> (bool success);
 
-  // Sets the observer for handling page navigation events.
-  //
-  // |observer|: The observer to use. Unregisters any existing observers
-  //             if null.
+  /// Sets the observer for handling page navigation events.
+  ///
+  /// |observer|: The observer to use. Unregisters any existing observers
+  ///             if null.
   SetNavigationEventObserver(NavigationEventObserver? observer);
 
-  // If set to a value other than NONE, allows web content to log messages
-  // to the system logger using console.log(), console.info(), console.warn(),
-  // and console.error().
+  /// If set to a value other than NONE, allows web content to log messages
+  /// to the system logger using console.log(), console.info(), console.warn(),
+  /// and console.error().
   SetJavaScriptLogLevel(LogLevel level);
 };
 
 struct WebMessage {
-  // The message payload, encoded as an UTF-8 string.
+  /// The message payload, encoded as an UTF-8 string.
   fuchsia.mem.Buffer data;
 
-  // List of objects transferred into the MessagePort from the FIDL client.
+  /// List of objects transferred into the MessagePort from the FIDL client.
   // TODO(crbug.com/893236): make this a vector when FIDL-354 is fixed.
   IncomingTransferable? incoming_transfer;
 
-  // List of objects transferred out of the MessagePort to the FIDL client.
+  /// List of objects transferred out of the MessagePort to the FIDL client.
   OutgoingTransferable? outgoing_transfer;
 };
 
@@ -112,19 +119,19 @@ union IncomingTransferable {
   MessagePort message_port;
 };
 
-// Represents one end of an HTML5 MessageChannel. Can be used to send
-// and exchange Messages with the peered MessagePort in the Frame's script
-// context. The port is destroyed when either end of the MessagePort channel
-// is torn down.
+/// Represents one end of an HTML5 MessageChannel. Can be used to send
+/// and exchange Messages with the peered MessagePort in the Frame's script
+/// context. The port is destroyed when either end of the MessagePort channel
+/// is torn down.
 interface MessagePort {
-  // Sends a WebMessage to the peer.
+  /// Sends a WebMessage to the peer.
   PostMessage(WebMessage message) -> (bool success);
 
-  // Asynchronously reads the next message from the channel.
-  // The client should invoke the callback when it is ready to process
-  // another message.
-  // Unreceived messages are buffered on the sender's side and bounded
-  // by its available resources.
+  /// Asynchronously reads the next message from the channel.
+  /// The client should invoke the callback when it is ready to process
+  /// another message.
+  /// Unreceived messages are buffered on the sender's side and bounded
+  /// by its available resources.
   ReceiveMessage() -> (WebMessage message);
 };
 

fuchsia/fidl/web/navigation_controller.fidl

@@ -4,14 +4,14 @@
 
 library chromium.web;
 
-// Provides methods for controlling and querying the navigation state
-// of a Frame.
+/// Provides methods for controlling and querying the navigation state
+/// of a Frame.
 interface NavigationController {
-  // Tells the Frame to navigate to a |url|.
-  //
-  // |url|:    The address to navigate to.
-  // |params|: Additional parameters that affect how the resource will be
-  //           loaded (e.g. cookies, HTTP headers, etc.)
+  /// Tells the Frame to navigate to a |url|.
+  ///
+  /// |url|:    The address to navigate to.
+  /// |params|: Additional parameters that affect how the resource will be
+  ///           loaded (e.g. cookies, HTTP headers, etc.)
   LoadUrl(string url, LoadUrlParams? params);
 
   GoBack();
@@ -19,48 +19,53 @@ interface NavigationController {
   Stop();
   Reload(ReloadType type);
 
-  // Returns information for the currently visible content regardless of
-  // loading state, or a null entry if no content is being displayed.
+  /// Returns information for the currently visible content regardless of
+  /// loading state, or a null entry if no content is being displayed.
   GetVisibleEntry() -> (NavigationEntry? entry);
 };
 
-// Additional parameters for modifying the behavior of LoadUrl().
+/// Additional parameters for modifying the behavior of LoadUrl().
 struct LoadUrlParams {
-  // Provides a hint to the browser UI about how LoadUrl was triggered.
+  /// Provides a hint to the browser UI about how LoadUrl was triggered.
   LoadUrlReason type;
 
-  // The URL that linked to the resource being requested.
+  /// The URL that linked to the resource being requested.
   string referrer;
 
-  // Should be set to true to propagate user activation to the frame. User
-  // activation implies that the user is interacting with the web frame. It
-  // enables some web features that are not available otherwise. For example
-  // autoplay will work only when this flag is set to true.
+  /// Should be set to true to propagate user activation to the frame. User
+  /// activation implies that the user is interacting with the web frame. It
+  /// enables some web features that are not available otherwise. For example
+  /// autoplay will work only when this flag is set to true.
   bool user_activated = false;
 
-  // Custom HTTP headers.
+  /// Custom HTTP headers.
   vector<vector<uint8>> headers;
 };
 
-// Characterizes the origin of a LoadUrl request.
+/// Characterizes the origin of a LoadUrl request.
 enum LoadUrlReason {
-  LINK = 0;   // Navigation was initiated by the user following a link.
-  TYPED = 1;  // Navigation was initiated by a user-provided URL.
+  /// Navigation was initiated by the user following a link.
+  LINK = 0;
+  /// Navigation was initiated by a user-provided URL.
+  TYPED = 1;
 };
 
-// Contains information about the Frame's navigation state.
-// The Frame's navigation history can be represented as an aggregation of
-// NavigationEntries.
+/// Contains information about the Frame's navigation state.
+/// The Frame's navigation history can be represented as an aggregation of
+/// NavigationEntries.
 struct NavigationEntry {
-  string url;     // The page's URL.
-  string title;   // The user-visible page title.
-  bool is_error;  // Indicates if an error occurred during this navigation.
+  /// The page's URL.
+  string url;
+  /// The user-visible page title.
+  string title;
+  /// Indicates if an error occurred during this navigation.
+  bool is_error;
 };
 
 enum ReloadType {
-  // Reloads the current entry, bypassing the cache for the main resource.
+  /// Reloads the current entry, bypassing the cache for the main resource.
   PARTIAL_CACHE = 0;
 
-  // Reloads the current entry, bypassing the cache entirely.
+  /// Reloads the current entry, bypassing the cache entirely.
   NO_CACHE = 1;
 };

fuchsia/fidl/web/navigation_event_observer.fidl

@@ -4,22 +4,22 @@
 
 library chromium.web;
 
-// Indicates the properties of the NavigationController's visible content
-// which have changed since the last OnNavigationStateChanged() event.
-// Any unchanged properties are left unset.
+/// Indicates the properties of the NavigationController's visible content
+/// which have changed since the last OnNavigationStateChanged() event.
+/// Any unchanged properties are left unset.
 struct NavigationEvent {
   string? url;
   string? title;
   bool is_error;
 };
 
-// Interface supplied by the embedder for receiving notifications about
-// navigation events in a Frame.
+/// Interface supplied by the embedder for receiving notifications about
+/// navigation events in a Frame.
 interface NavigationEventObserver {
-  // Called when user-visible navigation state has changed since Frame
-  // creation or the last acknowledgement callback, whichever occurred later.
-  // |change| will contain all the differences in navigation state since the
-  // last acknowledgement.
+  /// Called when user-visible navigation state has changed since Frame
+  /// creation or the last acknowledgement callback, whichever occurred later.
+  /// |change| will contain all the differences in navigation state since the
+  /// last acknowledgement.
   OnNavigationStateChanged(NavigationEvent change) -> ();
 };