Updated docs for next

releases/next/docs/native-modules-ios.html

@@ -4,9 +4,13 @@
 @interface <span class="token class-name">CalendarManager</span> <span class="token punctuation">:</span> NSObject &lt;RCTBridgeModule<span class="token operator">&gt;</span>
 @end</div><p>In addition to implementing the <code>RCTBridgeModule</code> protocol, your class must also include the <code>RCT_EXPORT_MODULE()</code> macro. This takes an optional argument that specifies the name that the module will be accessible as in your JavaScript code (more on this later). If you do not specify a name, the JavaScript module name will match the Objective-C class name.</p><div class="prism language-javascript"><span class="token comment" spellcheck="true">// CalendarManager.m
 </span>@implementation CalendarManager
-
-<span class="token function">RCT_EXPORT_MODULE<span class="token punctuation">(</span></span><span class="token punctuation">)</span><span class="token punctuation">;</span>
-
+<span class="token comment" spellcheck="true">
+// To export a module named CalendarManager
+</span><span class="token function">RCT_EXPORT_MODULE<span class="token punctuation">(</span></span><span class="token punctuation">)</span><span class="token punctuation">;</span>
+<span class="token comment" spellcheck="true">
+// This would name the module AwesomeCalendarManager instead
+</span><span class="token comment" spellcheck="true">// RCT_EXPORT_MODULE(AwesomeCalendarManager);
+</span>
 @end</div><p>React Native will not expose any methods of <code>CalendarManager</code> to JavaScript unless explicitly told to. This is done using the <code>RCT_EXPORT_METHOD()</code> macro:</p><div class="prism language-javascript">#import <span class="token string">&quot;CalendarManager.h&quot;</span>
 #import &lt;React<span class="token operator">/</span>RCTLog<span class="token punctuation">.</span>h<span class="token operator">&gt;</span>
 
@@ -43,13 +47,13 @@ CalendarManager<span class="token punctuation">.</span><span class="token functi
 <span class="token punctuation">{</span>
   NSArray <span class="token operator">*</span>events <span class="token operator">=</span> <span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span>
   <span class="token function">callback<span class="token punctuation">(</span></span>@<span class="token punctuation">[</span><span class="token punctuation">[</span>NSNull <span class="token keyword">null</span><span class="token punctuation">]</span><span class="token punctuation">,</span> events<span class="token punctuation">]</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
-<span class="token punctuation">}</span></div><p><code>RCTResponseSenderBlock</code> accepts only one argument - an array of parameters to pass to the JavaScript callback. In this case we use node&#x27;s convention to make the first parameter an error object (usually <code>null</code> when there is no error) and the rest are the results of the function.</p><div class="prism language-javascript">CalendarManager<span class="token punctuation">.</span><span class="token function">findEvents<span class="token punctuation">(</span></span><span class="token punctuation">(</span>error<span class="token punctuation">,</span> events<span class="token punctuation">)</span> <span class="token operator">=</span><span class="token operator">&gt;</span> <span class="token punctuation">{</span>
+<span class="token punctuation">}</span></div><p><code>RCTResponseSenderBlock</code> accepts only one argument - an array of parameters to pass to the JavaScript callback. In this case we use Node&#x27;s convention to make the first parameter an error object (usually <code>null</code> when there is no error) and the rest are the results of the function.</p><div class="prism language-javascript">CalendarManager<span class="token punctuation">.</span><span class="token function">findEvents<span class="token punctuation">(</span></span><span class="token punctuation">(</span>error<span class="token punctuation">,</span> events<span class="token punctuation">)</span> <span class="token operator">=</span><span class="token operator">&gt;</span> <span class="token punctuation">{</span>
   <span class="token keyword">if</span> <span class="token punctuation">(</span>error<span class="token punctuation">)</span> <span class="token punctuation">{</span>
     console<span class="token punctuation">.</span><span class="token function">error<span class="token punctuation">(</span></span>error<span class="token punctuation">)</span><span class="token punctuation">;</span>
   <span class="token punctuation">}</span> <span class="token keyword">else</span> <span class="token punctuation">{</span>
     <span class="token keyword">this</span><span class="token punctuation">.</span><span class="token function">setState<span class="token punctuation">(</span></span><span class="token punctuation">{</span>events<span class="token punctuation">:</span> events<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
   <span class="token punctuation">}</span>
-<span class="token punctuation">}</span><span class="token punctuation">)</span></div><p>A native module is supposed to invoke its callback only once. It can, however, store the callback and invoke it later. This pattern is often used to wrap iOS APIs that require delegates. See <a href="https://github.com/facebook/react-native/blob/master/React/Modules/RCTAlertManager.m" target="_blank"><code>RCTAlertManager</code></a> for an example.</p><p>If you want to pass error-like objects to JavaScript, use <code>RCTMakeError</code> from <a href="https://github.com/facebook/react-native/blob/master/React/Base/RCTUtils.h" target="_blank"><code>RCTUtils.h</code></a>.  Right now this just passes an Error-shaped dictionary to JavaScript, but we would like to automatically generate real JavaScript <code>Error</code> objects in the future.</p><h2><a class="anchor" name="promises"></a>Promises <a class="hash-link" href="docs/native-modules-ios.html#promises">#</a></h2><p>Native modules can also fulfill a promise, which can simplify your code, especially when using ES2016&#x27;s <code>async/await</code> syntax. When the last parameters of a bridged native method are an <code>RCTPromiseResolveBlock</code> and <code>RCTPromiseRejectBlock</code>, its corresponding JS method will return a JS Promise object.</p><p>Refactoring the above code to use a promise instead of callbacks looks like this:</p><div class="prism language-javascript"><span class="token function">RCT_REMAP_METHOD<span class="token punctuation">(</span></span>findEvents<span class="token punctuation">,</span>
+<span class="token punctuation">}</span><span class="token punctuation">)</span></div><p>A native module should invoke its callback exactly once. It&#x27;s okay to store the callback and invoke it later. This pattern is often used to wrap iOS APIs that require delegates - see <a href="https://github.com/facebook/react-native/blob/master/React/Modules/RCTAlertManager.m" target="_blank"><code>RCTAlertManager</code></a> for an example. If the callback is never invoked, some memory is leaked. If both <code>onSuccess</code> and <code>onFail</code> callbacks are passed, you should only invoke one of them.</p><p>If you want to pass error-like objects to JavaScript, use <code>RCTMakeError</code> from <a href="https://github.com/facebook/react-native/blob/master/React/Base/RCTUtils.h" target="_blank"><code>RCTUtils.h</code></a>.  Right now this just passes an Error-shaped dictionary to JavaScript, but we would like to automatically generate real JavaScript <code>Error</code> objects in the future.</p><h2><a class="anchor" name="promises"></a>Promises <a class="hash-link" href="docs/native-modules-ios.html#promises">#</a></h2><p>Native modules can also fulfill a promise, which can simplify your code, especially when using ES2016&#x27;s <code>async/await</code> syntax. When the last parameters of a bridged native method are an <code>RCTPromiseResolveBlock</code> and <code>RCTPromiseRejectBlock</code>, its corresponding JS method will return a JS Promise object.</p><p>Refactoring the above code to use a promise instead of callbacks looks like this:</p><div class="prism language-javascript"><span class="token function">RCT_REMAP_METHOD<span class="token punctuation">(</span></span>findEvents<span class="token punctuation">,</span>
                  resolver<span class="token punctuation">:</span><span class="token punctuation">(</span>RCTPromiseResolveBlock<span class="token punctuation">)</span>resolve
                  rejecter<span class="token punctuation">:</span><span class="token punctuation">(</span>RCTPromiseRejectBlock<span class="token punctuation">)</span>reject<span class="token punctuation">)</span>
 <span class="token punctuation">{</span>