From 28c9c68cfa51ea224466d9e0f1aac5ec39d220e0 Mon Sep 17 00:00:00 2001
From: Eli White <eliwhite@fb.com>
Date: Wed, 14 Mar 2018 14:30:44 -0700
Subject: [PATCH] Adding documentation to new StyleSheet Flow Types

Summary: Adding some explanation and examples of when to use these types.

Reviewed By: yungsters

Differential Revision: D7270185

fbshipit-source-id: c82f061ffb77e33133a59d268a08f7a95fd02fb6
---
 Libraries/StyleSheet/StyleSheet.js | 36 +++++++++++++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

diff --git a/Libraries/StyleSheet/StyleSheet.js b/Libraries/StyleSheet/StyleSheet.js
index 3320c459b..f2552f3e6 100644
--- a/Libraries/StyleSheet/StyleSheet.js
+++ b/Libraries/StyleSheet/StyleSheet.js
@@ -27,11 +27,45 @@ import type {
   LayoutStyle,
 } from 'StyleSheetTypes';
 
-export type DangerouslyImpreciseStyleProp = ____DangerouslyImpreciseStyleProp_Internal;
+/**
+ * This type should be used as the type for a prop that is passed through
+ * to a <View>'s `style` prop. This ensures call sites of the component
+ * can't pass styles that View doesn't support such as `fontSize`.`
+ *
+ * type Props = {style: ViewStyleProp}
+ * const MyComponent = (props: Props) => <View style={props.style} />
+ */
 export type ViewStyleProp = ____ViewStyleProp_Internal;
+
+/**
+ * This type should be used as the type for a prop that is passed through
+ * to a <Text>'s `style` prop. This ensures call sites of the component
+ * can't pass styles that Text doesn't support such as `resizeMode`.`
+ *
+ * type Props = {style: TextStyleProp}
+ * const MyComponent = (props: Props) => <Text style={props.style} />
+ */
 export type TextStyleProp = ____TextStyleProp_Internal;
+
+/**
+ * This type should be used as the type for a prop that is passed through
+ * to an <Image>'s `style` prop. This ensures call sites of the component
+ * can't pass styles that Image doesn't support such as `fontSize`.`
+ *
+ * type Props = {style: ImageStyleProp}
+ * const MyComponent = (props: Props) => <Image style={props.style} />
+ */
 export type ImageStyleProp = ____ImageStyleProp_Internal;
 
+/**
+ * WARNING: You probably shouldn't be using this type. This type
+ * is similar to the ones above except it allows styles that are accepted
+ * by all of View, Text, or Image. It is therefore very unsafe to pass this
+ * through to an underlying component. Using this is almost always a mistake
+ * and using one of the other more restrictive types is likely the right choice.
+ */
+export type DangerouslyImpreciseStyleProp = ____DangerouslyImpreciseStyleProp_Internal;
+
 let hairlineWidth = PixelRatio.roundToNearestPixel(0.4);
 if (hairlineWidth === 0) {
   hairlineWidth = 1 / PixelRatio.get();