From faa584c3bd2ce3625000cd424023cf4fc921aeeb Mon Sep 17 00:00:00 2001
From: Nick Lockwood <nicklockwood@fb.com>
Date: Fri, 6 Nov 2015 05:27:24 -0800
Subject: [PATCH] Added headerdoc for RCTBridgeDelegate

Reviewed By: javache

Differential Revision: D2622807

fb-gh-sync-id: 68d1e8cfd3beceafd07f041fa2976ac2552600f7
---
 React/Base/RCTBridge.m         |  5 +++++
 React/Base/RCTBridgeDelegate.h | 32 +++++++++++++++++++++++++++++---
 2 files changed, 34 insertions(+), 3 deletions(-)

diff --git a/React/Base/RCTBridge.m b/React/Base/RCTBridge.m
index 74f8b9a94..15f85c8da 100644
--- a/React/Base/RCTBridge.m
+++ b/React/Base/RCTBridge.m
@@ -11,6 +11,7 @@
 
 #import <objc/runtime.h>
 
+#import "RCTConvert.h"
 #import "RCTEventDispatcher.h"
 #import "RCTKeyCommands.h"
 #import "RCTLog.h"
@@ -250,6 +251,10 @@ RCT_NOT_IMPLEMENTED(- (instancetype)init)
   RCTAssertMainThread();
 
   _bundleURL = [self.delegate sourceURLForBridge:self] ?: _bundleURL;
+
+  // Sanitize the bundle URL
+  _bundleURL = [RCTConvert NSURL:_bundleURL.absoluteString];
+
   _batchedBridge = [[RCTBatchedBridge alloc] initWithParentBridge:self];
 }
 
diff --git a/React/Base/RCTBridgeDelegate.h b/React/Base/RCTBridgeDelegate.h
index 2e6e8387a..d8606c8d9 100644
--- a/React/Base/RCTBridgeDelegate.h
+++ b/React/Base/RCTBridgeDelegate.h
@@ -10,15 +10,41 @@
 typedef void (^RCTSourceLoadBlock)(NSError *error, NSData *source);
 
 @class RCTBridge;
-@protocol RCTBridgeModule;
 
 @protocol RCTBridgeDelegate <NSObject>
 
+/**
+ * The location of the JavaScript source file. When running from the packager
+ * this should be an absolute URL, e.g. `http://localhost:8081/index.ios.bundle`.
+ * When running from a locally bundled JS file, this should be a `file://` url
+ * pointing to a path inside the app resources, e.g. `file://.../main.jsbundle`.
+ */
 - (NSURL *)sourceURLForBridge:(RCTBridge *)bridge;
 
 @optional
 
-- (NSArray<id<RCTBridgeModule>> *)extraModulesForBridge:(RCTBridge *)bridge;
-- (void)loadSourceForBridge:(RCTBridge *)bridge withBlock:(RCTSourceLoadBlock)loadCallback;
+/**
+ * The bridge initializes any registered RCTBridgeModules automatically, however
+ * if you wish to instantiate your own module instances, you can return them
+ * from this method.
+ *
+ * Note: You should always return a new instance for each call, rather than
+ * returning the same instance each time the bridge is reloaded. Module instances
+ * should not be shared between bridges, and this may cause unexpected behavior.
+ *
+ * It is also possible to override standard modules with your own implementations
+ * by returning a class with the same `moduleName` from this method, but this is
+ * not recommended in most cases - if the module methods and behavior do not
+ * match exactly, it may lead to bugs or crashes.
+ */
+- (NSArray *)extraModulesForBridge:(RCTBridge *)bridge;
+
+/**
+ * The bridge will automatically attempt to load the JS source code from the
+ * location specified by the `sourceURLForBridge:` method, however, if you want
+ * to handle loading the JS yourself, you can do so by implementing this method.
+ */
+- (void)loadSourceForBridge:(RCTBridge *)bridge
+                  withBlock:(RCTSourceLoadBlock)loadCallback;
 
 @end