Add a bunch of docs

We're making an assumption here that the decorator is actually all over the app when it's not.

src/utils/replaceableComponent.ts

@@ -17,6 +17,24 @@ limitations under the License.
 import React from 'react';
 import sdk from '../index';
 
+/**
+ * Replaces a component with a skinned version if a skinned version exists.
+ * This decorator should only be applied to components which can be skinned. For
+ * the react-sdk this means all components should be decorated with this.
+ *
+ * The decoration works by assuming the skin has been loaded prior to the
+ * decorator being called. If that's not the case, the developer will find
+ * out quickly through various amounts of errors and explosions.
+ *
+ * For a bit more detail on how this works, see docs/skinning.md
+ * @param {string} name The dot-path name of the component being replaced.
+ * @param {React.Component} origComponent The component that can be replaced
+ * with a skinned version. If no skinned version is available, this component
+ * will be used.
+ */
 export function replaceableComponent(name: string, origComponent: React.Component) {
+    // Decorators return a function to override the class (origComponent). This
+    // ultimately assumes that `getComponent()` won't throw an error and instead
+    // return a falsey value like `null` when the skin doesn't have a component.
     return () => sdk.getComponent(name) || origComponent;
 }