Swipeables documentation

Summary: So users can know how to use

Reviewed By: hedgerwang

Differential Revision: D3399028

fbshipit-source-id: 5ce97c5464f1975145aba1bcf4b79550394859ae

Libraries/Experimental/SwipeableRow/SwipeableListView.js

@@ -32,7 +32,21 @@ const {PropTypes} = React;
 
 /**
  * A container component that renders multiple SwipeableRow's in a ListView
- * implementation.
+ * implementation. This is designed to be a drop-in replacement for the
+ * standard React Native `ListView`, so use it as if it were a ListView, but
+ * with extra props, i.e.
+ *
+ * let ds = SwipeableListView.getNewDataSource();
+ * ds.cloneWithRowsAndSections(dataBlob, ?sectionIDs, ?rowIDs);
+ * // ..
+ * <SwipeableListView renderRow={..} renderQuickActions={..} {..ListView props} />
+ *
+ * SwipeableRow can be used independently of this component, but the main
+ * benefit of using this component is
+ *
+ * - It ensures that at most 1 row is swiped open (auto closes others)
+ * - It can bounce the 1st row of the list so users know it's swipeable
+ * - More to come
  */
 const SwipeableListView = React.createClass({
   statics: {
@@ -50,8 +64,17 @@ const SwipeableListView = React.createClass({
   _shouldBounceFirstRowOnMount: false,
 
   propTypes: {
+    /**
+     * To alert the user that swiping is possible, the first row can bounce
+     * on component mount.
+     */
     bounceFirstRowOnMount: PropTypes.bool.isRequired,
+    /**
+     * Use `SwipeableListView.getNewDataSource()` to get a data source to use,
+     * then use it just like you would a normal ListView data source
+     */
     dataSource: PropTypes.instanceOf(SwipeableListViewDataSource).isRequired,
+    // Maximum distance to open to after a swipe
     maxSwipeDistance: PropTypes.number,
     // Callback method to render the swipeable view
     renderRow: PropTypes.func.isRequired,

Libraries/Experimental/SwipeableRow/SwipeableQuickActionButton.js

@@ -31,6 +31,11 @@ const View = require('View');
 
 const {PropTypes} = React;
 
+/**
+ * Standard set of quick action buttons that can, if the user chooses, be used
+ * with SwipeableListView. Each button takes an image and text with optional
+ * formatting.
+ */
 const SwipeableQuickActionButton = React.createClass({
   propTypes: {
     accessibilityLabel: PropTypes.string,

Libraries/Experimental/SwipeableRow/SwipeableQuickActions.js

@@ -29,6 +29,16 @@ const View = require('View');
 
 const MAX_QUICK_ACTIONS = 2;
 
+/**
+ * A thin wrapper around standard quick action buttons that can, if the user
+ * chooses, be used with SwipeableListView. Sample usage is as follows, in the
+ * renderQuickActions callback:
+ *
+ * <SwipeableQuickActions>
+ *   <SwipeableQuickActionButton {..props} />
+ *   <SwipeableQuickActionButton {..props} />
+ * </SwipeableQuickActions>
+ */
 const SwipeableQuickActions = React.createClass({
   propTypes: {
     style: View.propTypes.style,

Libraries/Experimental/SwipeableRow/SwipeableRow.js

@@ -65,7 +65,10 @@ const RIGHT_SWIPE_THRESHOLD = 30 * SLOW_SPEED_SWIPE_FACTOR;
 
 /**
  * Creates a swipable row that allows taps on the main item and a custom View
- * on the item hidden behind the row
+ * on the item hidden behind the row. Typically this should be used in
+ * conjunction with SwipeableListView for additional functionality, but can be
+ * used in a normal ListView. See the renderRow for SwipeableListView to see how
+ * to use this component separately.
  */
 const SwipeableRow = React.createClass({
   _panResponder: {},