From 2a4d926ab7a2724a3ce63293766efc70a0f9b58d Mon Sep 17 00:00:00 2001
From: Mikkel Nygaard Ravn <mravn@google.com>
Date: Tue, 5 Jun 2018 08:19:07 +0200
Subject: [PATCH] Update FlutterPluginRegistrxxx docs for iOS (#5415)

---
 .../ios/framework/Headers/FlutterPlugin.h     | 38 +++++++++++++++++--
 1 file changed, 34 insertions(+), 4 deletions(-)

diff --git a/shell/platform/darwin/ios/framework/Headers/FlutterPlugin.h b/shell/platform/darwin/ios/framework/Headers/FlutterPlugin.h
index 1fe71dd8b..ae6b730fa 100644
--- a/shell/platform/darwin/ios/framework/Headers/FlutterPlugin.h
+++ b/shell/platform/darwin/ios/framework/Headers/FlutterPlugin.h
@@ -24,11 +24,22 @@ NS_ASSUME_NONNULL_BEGIN
 @protocol FlutterPlugin <NSObject>
 @required
 /**
- Registers this plugin.
+ Registers this plugin using the context information and callback registration
+ methods exposed by the given registrar.
+
+ The registrar is obtained from a `FlutterPluginRegistry` which keeps track of
+ the identity of registered plugins and provides basic support for cross-plugin
+ coordination.
+
+ The caller of this method, a plugin registrant, is usually autogenerated by
+ Flutter tooling based on declared plugin dependencies. The generated registrant
+ asks the registry for a registrar for each plugin, and calls this method to
+ allow the plugin to initialize itself and register callbacks with application
+ objects available through the registrar protocol.
 
  - Parameters:
    - registrar: A helper providing application context and methods for
-     registering callbacks
+     registering callbacks.
  */
 + (void)registerWithRegistrar:(NSObject<FlutterPluginRegistrar>*)registrar;
 @optional
@@ -158,7 +169,13 @@ NS_ASSUME_NONNULL_BEGIN
 @end
 
 /**
- Registration context for a single `FlutterPlugin`.
+ Registration context for a single `FlutterPlugin`, providing a one stop shop
+ for the plugin to access contextual information and register callbacks for
+ various application events.
+
+ Registrars are obtained from a `FlutterPluginRegistry` which keeps track of
+ the identity of registered plugins and provides basic support for cross-plugin
+ coordination.
  */
 @protocol FlutterPluginRegistrar <NSObject>
 /**
@@ -234,7 +251,20 @@ NS_ASSUME_NONNULL_BEGIN
  A registry of Flutter iOS plugins.
 
  Plugins are identified by unique string keys, typically the name of the
- plugin's main class.
+ plugin's main class. The registry tracks plugins by this key, mapping it to
+ a value published by the plugin during registration, if any. This provides a
+ very basic means of cross-plugin coordination with loose coupling between
+ unrelated plugins.
+
+ Plugins typically need contextual information and the ability to register
+ callbacks for various application events. To keep the API of the registry
+ focused, these facilities are not provided directly by the registry, but by
+ a `FlutterPluginRegistrar`, created by the registry in exchange for the unique
+ key of the plugin.
+
+ There is no implied connection between the registry and the registrar.
+ Specifically, callbacks registered by the plugin via the registrar may be
+ relayed directly to the underlying iOS application objects.
  */
 @protocol FlutterPluginRegistry <NSObject>
 /**
-- 
GitLab