Fix -Wdocumentation warnings (facebookarchive#3113)

Author: maicki

Source/ASControlNode.mm

@@ -59,7 +59,6 @@ @interface ASControlNode ()
   @abstract Enumerates the ASControlNode events included mask, invoking the block for each event.
   @param mask An ASControlNodeEvent mask.
   @param block The block to be invoked for each ASControlNodeEvent included in mask.
-  @param anEvent An even that is included in mask.
  */
 void _ASEnumerateControlEventsIncludedInMaskWithBlock(ASControlNodeEvent mask, void (^block)(ASControlNodeEvent anEvent));
 

Source/ASDisplayNode.h

@@ -752,7 +752,7 @@ extern NSInteger const ASDefaultDrawingPriority;
  *
  * @param animated Animation is optional, but will still proceed through your `animateLayoutTransition` implementation with `isAnimated == NO`.
  * @param shouldMeasureAsync Measure the layout asynchronously.
- * @param measurementCompletion Optional completion block called only if a new layout is calculated.
+ * @param completion Optional completion block called only if a new layout is calculated.
  * It is called on main, right after the measurement and before -animateLayoutTransition:.
  *
  * @discussion If the passed constrainedSize is the the same as the node's current constrained size, this method is noop. If passed YES to shouldMeasureAsync it's guaranteed that measurement is happening on a background thread, otherwise measaurement will happen on the thread that the method was called on. The measurementCompletion callback is always called on the main thread right after the measurement and before -animateLayoutTransition:.
@@ -773,7 +773,7 @@ extern NSInteger const ASDefaultDrawingPriority;
  *
  * @param animated Animation is optional, but will still proceed through your `animateLayoutTransition` implementation with `isAnimated == NO`.
  * @param shouldMeasureAsync Measure the layout asynchronously.
- * @param measurementCompletion Optional completion block called only if a new layout is calculated.
+ * @param completion Optional completion block called only if a new layout is calculated.
  *
  * @see animateLayoutTransition:
  *

Source/ASDisplayNode.mm

@@ -466,8 +466,10 @@ - (void)_scheduleIvarsForMainDeallocation
  * up through ASDisplayNode, that we expect may need to be deallocated on main.
  * 
  * This method caches its results.
+ *
+ * Result is of type NSValue<[Ivar]>
  */
-+ (NSValue/*<[Ivar]>*/ * _Nonnull)_ivarsThatMayNeedMainDeallocation
++ (NSValue * _Nonnull)_ivarsThatMayNeedMainDeallocation
 {
   static NSCache<Class, NSValue *> *ivarsCache;
   static dispatch_once_t onceToken;

Source/ASMultiplexImageNode.mm

@@ -116,7 +116,6 @@ - (void)_loadNextImage;
   @param imageIdentifier The identifier for the image to be fetched. May not be nil.
   @param imageURL The URL of the image to fetch. May not be nil.
   @param completionBlock The block to be performed when the image has been fetched from the cache, if possible. May not be nil.
-  @param image The image fetched from the cache, if any.
   @discussion This method queries both the session's in-memory and on-disk caches (with preference for the in-memory cache).
  */
 - (void)_fetchImageWithIdentifierFromCache:(id)imageIdentifier URL:(NSURL *)imageURL completion:(void (^)(UIImage *image))completionBlock;
@@ -127,8 +126,6 @@ - (void)_fetchImageWithIdentifierFromCache:(id)imageIdentifier URL:(NSURL *)imag
   @param imageIdentifier The identifier for the image to be loaded. May not be nil.
   @param assetURL The assets-library URL (e.g., "assets-library://identifier") of the image to load, from ALAsset. May not be nil.
   @param completionBlock The block to be performed when the image has been loaded, if possible. May not be nil.
-  @param image The image that was loaded. May be nil if no image could be downloaded.
-  @param error An error describing why the load failed, if it failed; nil otherwise.
  */
 - (void)_loadALAssetWithIdentifier:(id)imageIdentifier URL:(NSURL *)assetURL completion:(void (^)(UIImage *image, NSError *error))completionBlock;
 
@@ -137,8 +134,6 @@ - (void)_loadALAssetWithIdentifier:(id)imageIdentifier URL:(NSURL *)assetURL com
   @param imageIdentifier The identifier for the image to be loaded. May not be nil.
   @param request The photos image request to load. May not be nil.
   @param completionBlock The block to be performed when the image has been loaded, if possible. May not be nil.
-  @param image The image that was loaded. May be nil if no image could be downloaded.
-  @param error An error describing why the load failed, if it failed; nil otherwise.
  */
 - (void)_loadPHAssetWithRequest:(ASPhotosFrameworkImageRequest *)request identifier:(id)imageIdentifier completion:(void (^)(UIImage *image, NSError *error))completionBlock;
 #endif
@@ -147,8 +142,6 @@ - (void)_loadPHAssetWithRequest:(ASPhotosFrameworkImageRequest *)request identif
  @param imageIdentifier The identifier for the image to be downloaded. May not be nil.
  @param imageURL The URL of the image to downloaded. May not be nil.
  @param completionBlock The block to be performed when the image has been downloaded, if possible. May not be nil.
- @param image The image that was downloaded. May be nil if no image could be downloaded.
- @param error An error describing why the download failed, if it failed; nil otherwise.
  */
 - (void)_downloadImageWithIdentifier:(id)imageIdentifier URL:(NSURL *)imageURL completion:(void (^)(UIImage *image, NSError *error))completionBlock;
 

Source/ASTableNode.h

@@ -463,7 +463,7 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  * Similar to -tableView:cellForRowAtIndexPath:.
  *
- * @param tableNode The sender.
+ * @param tableView The sender.
  *
  * @param indexPath The index path of the requested node.
  *
@@ -552,7 +552,7 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  * Receive a message that the tableView is near the end of its data set and more data should be fetched if necessary.
  *
- * @param tableView The sender.
+ * @param tableNode The sender.
  * @param context A context object that must be notified when the batch fetch is completed.
  *
  * @discussion You must eventually call -completeBatchFetching: with an argument of YES in order to receive future
@@ -566,7 +566,7 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  * Tell the tableView if batch fetching should begin.
  *
- * @param tableView The sender.
+ * @param tableNode The sender.
  *
  * @discussion Use this method to conditionally fetch batches. Example use cases are: limiting the total number of
  * objects that can be fetched or no network connection.

Source/ASVideoNode.h

@@ -110,13 +110,13 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  * @abstract Delegate method invoked when player playback time is updated.
  * @param videoNode The video node.
- * @param second current playback time in seconds.
+ * @param timeInterval current playback time in seconds.
  */
 - (void)videoNode:(ASVideoNode *)videoNode didPlayToTimeInterval:(NSTimeInterval)timeInterval;
 /**
  * @abstract Delegate method invoked when the video player stalls.
  * @param videoNode The video node that has experienced the stall
- * @param second Current playback time when the stall happens
+ * @param timeInterval Current playback time when the stall happens
  */
 - (void)videoNode:(ASVideoNode *)videoNode didStallAtTimeInterval:(NSTimeInterval)timeInterval;
 /**

Source/ASVideoPlayerNode.h

@@ -80,22 +80,22 @@ NS_ASSUME_NONNULL_BEGIN
 @optional
 /**
  * @abstract Delegate method invoked before creating controlbar controls
- * @param videoPlayer
+ * @param videoPlayer The sender
  */
 - (NSArray *)videoPlayerNodeNeededDefaultControls:(ASVideoPlayerNode*)videoPlayer;
 
 /**
  * @abstract Delegate method invoked before creating default controls, asks delegate for custom controls dictionary.
  * This dictionary must constain only ASDisplayNode subclass objects.
- * @param videoPlayer
+ * @param videoPlayer The sender
  * @discussion - This method is invoked only when developer implements videoPlayerNodeLayoutSpec:forControls:forMaximumSize:
  * and gives ability to add custom constrols to ASVideoPlayerNode, for example mute button.
  */
 - (NSDictionary *)videoPlayerNodeCustomControls:(ASVideoPlayerNode*)videoPlayer;
 
 /**
  * @abstract Delegate method invoked in layoutSpecThatFits:
- * @param videoPlayer
+ * @param videoPlayer The sender
  * @param controls - Dictionary of controls which are used in videoPlayer; Dictionary keys are ASVideoPlayerNodeControlType
  * @param maxSize - Maximum size for ASVideoPlayerNode
  * @discussion - Developer can layout whole ASVideoPlayerNode as he wants. ASVideoNode is locked and it can't be changed
@@ -107,10 +107,10 @@ NS_ASSUME_NONNULL_BEGIN
 #pragma mark Text delegate methods
 /**
  * @abstract Delegate method invoked before creating ASVideoPlayerNodeControlTypeElapsedText and ASVideoPlayerNodeControlTypeDurationText
- * @param videoPlayer
- * @param timeLabelType
+ * @param videoPlayer The sender
+ * @param timeLabelType The of the time label
  */
-- (NSDictionary *)videoPlayerNodeTimeLabelAttributes:(ASVideoPlayerNode *)videoPlayerNode timeLabelType:(ASVideoPlayerNodeControlType)timeLabelType;
+- (NSDictionary *)videoPlayerNodeTimeLabelAttributes:(ASVideoPlayerNode *)videoPlayer timeLabelType:(ASVideoPlayerNodeControlType)timeLabelType;
 - (NSString *)videoPlayerNode:(ASVideoPlayerNode *)videoPlayerNode
    timeStringForTimeLabelType:(ASVideoPlayerNodeControlType)timeLabelType
                       forTime:(CMTime)time;
@@ -136,7 +136,7 @@ NS_ASSUME_NONNULL_BEGIN
 #pragma mark ASVideoNodeDelegate proxy methods
 /**
  * @abstract Delegate method invoked when ASVideoPlayerNode is taped.
- * @param videoPlayerNode The ASVideoPlayerNode that was tapped.
+ * @param videoPlayer The ASVideoPlayerNode that was tapped.
  */
 - (void)didTapVideoPlayerNode:(ASVideoPlayerNode *)videoPlayer;
 
@@ -148,23 +148,23 @@ NS_ASSUME_NONNULL_BEGIN
 
 /**
  * @abstract Delegate method invoked when ASVideoNode playback time is updated.
- * @param videoPlayerNode The video player node
- * @param second current playback time.
+ * @param videoPlayer The video player node
+ * @param time current playback time.
  */
 - (void)videoPlayerNode:(ASVideoPlayerNode *)videoPlayer didPlayToTime:(CMTime)time;
 
 /**
  * @abstract Delegate method invoked when ASVideoNode changes state.
- * @param videoPlayerNode The ASVideoPlayerNode whose ASVideoNode is changing state.
+ * @param videoPlayer The ASVideoPlayerNode whose ASVideoNode is changing state.
  * @param state ASVideoNode state before this change.
- * @param toSate ASVideoNode new state.
+ * @param toState ASVideoNode new state.
  * @discussion This method is called after each state change
  */
 - (void)videoPlayerNode:(ASVideoPlayerNode *)videoPlayer willChangeVideoNodeState:(ASVideoNodePlayerState)state toVideoNodeState:(ASVideoNodePlayerState)toState;
 
 /**
  * @abstract Delegate method is invoked when ASVideoNode decides to change state.
- * @param videoPlayerNode The ASVideoPlayerNode whose ASVideoNode is changing state.
+ * @param videoPlayer The ASVideoPlayerNode whose ASVideoNode is changing state.
  * @param state ASVideoNode that is going to be set.
  * @discussion Delegate method invoked when player changes it's state to
  * ASVideoNodePlayerStatePlaying or ASVideoNodePlayerStatePaused
@@ -188,7 +188,7 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  * @abstract Delegate method invoked when the ASVideoNode stalls.
  * @param videoPlayer The video player node that has experienced the stall
- * @param second Current playback time when the stall happens
+ * @param timeInterval Current playback time when the stall happens
  */
 - (void)videoPlayerNode:(ASVideoPlayerNode *)videoPlayer didStallAtTimeInterval:(NSTimeInterval)timeInterval;
 

Source/Debug/AsyncDisplayKit+Debug.h

@@ -21,7 +21,7 @@ NS_ASSUME_NONNULL_BEGIN
  * Enables an ASImageNode debug label that shows the ratio of pixels in the source image to those in
  * the displayed bounds (including cropRect).  This helps detect excessive image fetching / downscaling,
  * as well as upscaling (such as providing a URL not suitable for a Retina device).  For dev purposes only.
- * @param enabled Specify YES to show the label on all ASImageNodes with non-1.0x source-to-bounds pixel ratio.
+ * Specify YES to show the label on all ASImageNodes with non-1.0x source-to-bounds pixel ratio.
  */
 @property (class, nonatomic) BOOL shouldShowImageScalingOverlay;
 
@@ -36,7 +36,7 @@ NS_ASSUME_NONNULL_BEGIN
  * edges that are clipped by the tappable area of any parent (their bounds + hitTestSlop) in the hierarchy = DARK GREEN BORDERED EDGE,
  * edges that are clipped by clipToBounds = YES of any parent in the hierarchy = ORANGE BORDERED EDGE (may still receive touches beyond
  * overlay rect, but can't be visualized).
- * @param enable Specify YES to make this debug feature enabled when messaging the ASControlNode class.
+ * Specify YES to make this debug feature enabled when messaging the ASControlNode class.
  */
 @property (class, nonatomic) BOOL enableHitTestDebug;
 

Source/Details/ASImageProtocols.h

@@ -30,7 +30,6 @@ typedef void(^ASImageCacherCompletion)(id <ASImageContainerProtocol> _Nullable i
  @param URL The URL of the image to retrieve from the cache.
  @param callbackQueue The queue to call `completion` on.
  @param completion The block to be called when the cache has either hit or missed.
- @param imageFromCache The image that was retrieved from the cache, if the image could be retrieved; nil otherwise.
  @discussion If `URL` is nil, `completion` will be invoked immediately with a nil image. This method should not block
  the calling thread as it is likely to be called from the main thread.
  */
@@ -51,7 +50,7 @@ typedef void(^ASImageCacherCompletion)(id <ASImageContainerProtocol> _Nullable i
  the calling thread to fetch the image from a fast memory cache. It is OK to return nil from this method and instead
  support only cachedImageWithURL:callbackQueue:completion: however, synchronous rendering will not be possible.
  */
-- (nullable id <ASImageContainerProtocol>)synchronouslyFetchedCachedImageWithURL:(NSURL *)URL;
+- (nullable id <ASImageContainerProtocol>)synchronouslyFetchedCachedImageWithURL:(nullable NSURL *)URL;
 
 /**
  @abstract Called during clearPreloadedData. Allows the cache to optionally trim items.
@@ -144,8 +143,7 @@ withDownloadIdentifier:(id)downloadIdentifier;
 @optional
 
 /**
- @abstract Should be called when the objects cover image is ready.
- @param coverImageReadyCallback a block which receives the cover image.
+ @abstract A block which receives the cover image. Should be called when the objects cover image is ready.
  */
 @property (nonatomic, strong, readwrite) void (^coverImageReadyCallback)(UIImage *coverImage);
 

Source/Private/ASBatchFetching.h

@@ -28,10 +28,10 @@ ASDISPLAYNODE_EXTERN_C_BEGIN
  @abstract Determine if batch fetching should begin based on the state of the parameters.
  @discussion This method is broken into a category for unit testing purposes and should be used with the ASTableView and
  * ASCollectionView batch fetching API.
- @param context The scroll view that in-flight fetches are happening.
+ @param scrollView The scroll view that in-flight fetches are happening.
  @param scrollDirection The current scrolling direction of the scroll view.
  @param scrollableDirections The possible scrolling directions of the scroll view.
- @param targetOffset The offset that the scrollview will scroll to.
+ @param contentOffset The offset that the scrollview will scroll to.
  @return Whether or not the current state should proceed with batch fetching.
  */
 BOOL ASDisplayShouldFetchBatchForScrollView(UIScrollView<ASBatchFetchingScrollView> *scrollView, ASScrollDirection scrollDirection, ASScrollDirection scrollableDirections, CGPoint contentOffset);