Event handling for iOS - how hitTest:withEvent: and pointInside:withEvent: are related?

I think you are confusing subclassing with the view hierarchy. What the doc says is as follows. Say you have this view hierarchy. By hierarchy I'm not talking about class hierarchy, but views within views hierarchy, as follows:

+----------------------------+
|A                           |
|+--------+   +------------+ |
||B       |   |C           | |
||        |   |+----------+| |
|+--------+   ||D         || |
|             |+----------+| |
|             +------------+ |
+----------------------------+

Say you put your finger inside D. Here's what will happen:

1. hitTest:withEvent: is called on A, the top-most view of the view hierarchy.
2. pointInside:withEvent: is called recursively on each view.
   1. pointInside:withEvent: is called on A, and returns YES
   2. pointInside:withEvent: is called on B, and returns NO
   3. pointInside:withEvent: is called on C, and returns YES
   4. pointInside:withEvent: is called on D, and returns YES
3. On the views that returned YES, it will look down on the hierarchy to see the subview where the touch took place. In this case, from A, C and D, it will be D.
4. D will be the hit-test view

It seems quite a basic question. But I agree with you the document is not as clear as other documents, so here is my answer.

The implementation of hitTest:withEvent: in UIResponder does the following:

• It calls pointInside:withEvent: of self
• If the return is NO, hitTest:withEvent: returns nil. the end of the story.
• If the return is YES, it sends hitTest:withEvent: messages to its subviews. it starts from the top-level subview, and continues to other views until a subview returns a non-nil object, or all subviews receive the message.
• If a subview returns a non-nil object in the first time, the first hitTest:withEvent: returns that object. the end of the story.
• If no subview returns a non-nil object, the first hitTest:withEvent: returns self

This process repeats recursively, so normally the leaf view of the view hierarchy is returned eventually.

However, you might override hitTest:withEvent to do something differently. In many cases, overriding pointInside:withEvent: is simpler and still provides enough options to tweak event handling in your application.

I find this Hit-Testing in iOS to be very helpful

- (UIView *)hitTest:(CGPoint)point withEvent:(UIEvent *)event {
    if (!self.isUserInteractionEnabled || self.isHidden || self.alpha <= 0.01) {
        return nil;
    }
    if ([self pointInside:point withEvent:event]) {
        for (UIView *subview in [self.subviews reverseObjectEnumerator]) {
            CGPoint convertedPoint = [subview convertPoint:point fromView:self];
            UIView *hitTestView = [subview hitTest:convertedPoint withEvent:event];
            if (hitTestView) {
                return hitTestView;
            }
        }
        return self;
    }
    return nil;
}

Edit Swift 4:

override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
    if self.point(inside: point, with: event) {
        return super.hitTest(point, with: event)
    }
    guard isUserInteractionEnabled, !isHidden, alpha > 0 else {
        return nil
    }

    for subview in subviews.reversed() {
        let convertedPoint = subview.convert(point, from: self)
        if let hitView = subview.hitTest(convertedPoint, with: event) {
            return hitView
        }
    }
    return nil
}