[Documentation] Improve ASVisibility protocol documentation (#2319)

* Improve ASNavigationController, ASTabBarController and ASVisibility protocol documentation.

* Spelling and grammar fixes. Thanks @hannahmbanana!

AsyncDisplayKit/ASNavigationController.h

@@ -16,6 +16,14 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/**
+ * ASNavigationController
+ *
+ * @discussion ASNavigationController is a drop in replacement for UINavigationController
+ * which implements the memory efficiency improving @c ASManagesChildVisibilityDepth protocol.
+ *
+ * @see ASManagesChildVisibilityDepth
+ */
 @interface ASNavigationController : UINavigationController <ASManagesChildVisibilityDepth>
 
 @end

AsyncDisplayKit/ASTabBarController.h

@@ -16,6 +16,14 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/**
+ * ASTabBarController
+ *
+ * @discussion ASTabBarController is a drop in replacement for UITabBarController
+ * which implements the memory efficiency improving @c ASManagesChildVisibilityDepth protocol.
+ *
+ * @see ASManagesChildVisibilityDepth
+ */
 @interface ASTabBarController : UITabBarController <ASManagesChildVisibilityDepth>
 
 @end

AsyncDisplayKit/ASVisibilityProtocols.h

@@ -24,10 +24,22 @@ extern ASLayoutRangeMode ASLayoutRangeModeForVisibilityDepth(NSUInteger visibili
 
 ASDISPLAYNODE_EXTERN_C_END
 
+/**
+ * ASVisibilityDepth
+ *
+ * @discussion A protocol which when implemented represents the number of user actions required to
+ * make an ASDisplayNode or ASViewController visible. Parent view controllers should also implement
+ * @c ASManagesChildVisibilityDepth
+ *
+ * @see ASManagesChildVisibilityDepth
+ */
+
 @protocol ASVisibilityDepth <NSObject>
 
 /**
- * @abstract Represents the number of user actions necessary to reach the view controller. An increased visibility
+ * Visibility depth
+ *
+ * @discussion Represents the number of user actions necessary to reach the view controller. An increased visibility
  * depth indicates a higher number of user interactions for the view controller to be visible again. For example,
  * an onscreen navigation controller's top view controller should have a visibility depth of 0. The view controller
  * one from the top should have a visibility deptch of 1 as should the root view controller in the stack (because
@@ -38,11 +50,38 @@ ASDISPLAYNODE_EXTERN_C_END
  */
 - (NSInteger)visibilityDepth;
 
-
+/**
+ * Called when visibility depth changes
+ *
+ * @discussion @c visibilityDepthDidChange is called whenever the visibility depth of the represented view controller
+ * has changed.
+ * 
+ * If implemented by a view controller container, use this method to notify child view controllers that their view
+ * depth has changed @see ASNavigationController.m
+ *
+ * If implemented on an ASViewController, use this method to reduce or increase the resources that your
+ * view controller uses. A higher visibility depth view controller should decrease it's resource usage, a lower
+ * visibility depth controller should pre-warm resources in preperation for a display at 0 depth.
+ *
+ * ASViewController implements this method and reduces / increases range mode of supporting nodes (such as ASCollectionNode
+ * and ASTableNode).
+ *
+ * @see visibilityDepth
+ */
 - (void)visibilityDepthDidChange;
 
 @end
 
+/**
+ * ASManagesChildVisibilityDepth
+ *
+ * @discussion A protocol which should be implemented by container view controllers to allow proper
+ * propagation of visibility depth
+ *
+ * @see ASVisibilityDepth
+ */
+@protocol ASManagesChildVisibilityDepth <ASVisibilityDepth>
+
 /**
  * @abstract Container view controllers should adopt this protocol to indicate that they will manage their child's
  * visibilityDepth. For example, ASNavigationController adopts this protocol and manages its childrens visibility
@@ -52,8 +91,6 @@ ASDISPLAYNODE_EXTERN_C_END
  *
  * @param childViewController Expected to return the visibility depth of the child view controller.
  */
-@protocol ASManagesChildVisibilityDepth <ASVisibilityDepth>
-
 - (NSInteger)visibilityDepthOfChildViewController:(UIViewController *)childViewController;
 
 @end