From 381e2acd184fc4ba80a240ba3d7dda0464c6416b Mon Sep 17 00:00:00 2001
From: Kyle Corbitt <kyle@corbt.com>
Date: Wed, 7 Oct 2015 09:32:35 -0700
Subject: [PATCH] Document NativeMethodsMixin
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Summary: This is related to the discussion in #3155.

I've documented the methods in this mixin, and pointed to other appropriate documentation where necessary as well.

I didn't end up adding any examples. I wanted to add a `focus()`/`blur()` example to the UIExplorer app, but the app seems to be broken on master at the moment (`Requiring unknown module "event-target-shim"`) and I didn't bother trying to fix it. I think the last thing necessary for making the usage of these methods clear is an example of calling one or more of them on a `ref` or view captured in some other way. However, `setNativeProps` is well documented in the "Direct Manipulation" guide, which I link to from this page, so by extension it should be possible to figure out the functionality of the other methods.

cc @mkonicek @​astreet
Closes https://github.com/facebook/react-native/pull/3238

Reviewed By: @​svcscm

Differential Revision: D2517187

Pulled By: @mkonicek

fb-gh-sync-id: 4e68b2bc44ace83f06ae2e364ca0c23a7c461b20
---
 Libraries/ReactIOS/NativeMethodsMixin.js | 52 ++++++++++++++++++++++--
 1 file changed, 48 insertions(+), 4 deletions(-)

diff --git a/Libraries/ReactIOS/NativeMethodsMixin.js b/Libraries/ReactIOS/NativeMethodsMixin.js
index 4da11abc7..b2b5ba419 100644
--- a/Libraries/ReactIOS/NativeMethodsMixin.js
+++ b/Libraries/ReactIOS/NativeMethodsMixin.js
@@ -35,7 +35,6 @@ type MeasureLayoutOnSuccessCallback = (
   height: number
 ) => void
 
-
 function warnForStyleProps(props, validAttributes) {
   for (var key in validAttributes.style) {
     if (!(validAttributes[key] || props[key] === undefined)) {
@@ -48,7 +47,36 @@ function warnForStyleProps(props, validAttributes) {
   }
 }
 
+/**
+ * `NativeMethodsMixin` provides methods to access the underlying native
+ * component directly. This can be useful in cases when you want to focus
+ * a view or measure its on-screen dimensions, for example.
+ *
+ * The methods described here are available on most of the default components
+ * provided by React Native. Note, however, that they are *not* available on
+ * composite components that aren't directly backed by a native view. This will
+ * generally include most components that you define in your own app. For more
+ * information, see [Direct
+ * Manipulation](/react-native/docs/direct-manipulation.html).
+ */
 var NativeMethodsMixin = {
+  /**
+   * Determines the location on screen, width, and height of the given view and
+   * returns the values via an async callback. If successful, the callback will
+   * be called with the following arguments:
+   *
+   *  - x
+   *  - y
+   *  - width
+   *  - height
+   *  - pageX
+   *  - pageY
+   *
+   * Note that these measurements are not available until after the rendering
+   * has been completed in native. If you need the measurements as soon as
+   * possible, consider using the [`onLayout`
+   * prop](/react-native/docs/view.html#onlayout) instead.
+   */
   measure: function(callback: MeasureOnSuccessCallback) {
     RCTUIManager.measure(
       findNodeHandle(this),
@@ -56,6 +84,14 @@ var NativeMethodsMixin = {
     );
   },
 
+  /**
+   * Like [`measure()`](#measure), but measures the view relative an ancestor,
+   * specified as `relativeToNativeNode`. This means that the returned x, y
+   * are relative to the origin x, y of the ancestor view.
+   *
+   * As always, to obtain a native node handle for a component, you can use
+   * `React.findNodeHandle(component)`.
+   */
   measureLayout: function(
     relativeToNativeNode: number,
     onSuccess: MeasureLayoutOnSuccessCallback,
@@ -70,9 +106,10 @@ var NativeMethodsMixin = {
   },
 
   /**
-   * This function sends props straight to native. They will not participate
-   * in future diff process, this means that if you do not include them in the
-   * next render, they will remain active.
+   * This function sends props straight to native. They will not participate in
+   * future diff process - this means that if you do not include them in the
+   * next render, they will remain active (see [Direct
+   * Manipulation](/react-native/docs/direct-manipulation.html)).
    */
   setNativeProps: function(nativeProps: Object) {
     if (__DEV__) {
@@ -91,10 +128,17 @@ var NativeMethodsMixin = {
     );
   },
 
+  /**
+   * Requests focus for the given input or view. The exact behavior triggered
+   * will depend on the platform and type of view.
+   */
   focus: function() {
     TextInputState.focusTextInput(findNodeHandle(this));
   },
 
+  /**
+   * Removes focus from an input or view. This is the opposite of `focus()`.
+   */
   blur: function() {
     TextInputState.blurTextInput(findNodeHandle(this));
   }