NSTreeController's add, addChild, insert and insertChild methods

I had a hard time interpreting Apple's documentation of NSTreeController's mutator methods and their corresponding canXyz methods. My experiments did reveal symmetry in and consistency among the semantics of these methods, it's just that their naming is a bit odd (I say that coming from a strong Java background). The docs didn't help much either. I only investigated NSTreeController in entity mode, but I would guess that these methods behave identically in object mode as far as the pre-conditions and the position of the new node are concerned.

• add: Creates a new entity and makes it the last sibling of the selected entity. IOW, the new entity becomes the last child of the selected entity's parent. Without a selection, the entity becomes the last top-level (orphan) entity. Think appendSibling.
• canAdd: Have never observed it to be false.
• insert: Creates a new entity and makes it a sibling of the selected entity, immediately preceding it. Without a selection, the entity becomes the first top-level entity. Think prependSibling.
• canInsert: Have never observed it to be false.
• addChild: Does nothing if the selected entity is a leaf. Otherwise, creates a new entity and adds it as the last child of the selection. Think appendChild.
• canAddChild: False if selection is a leaf.
• insertChild: Does nothing if the selected entity is a leaf. Otherwise, creates a new entity and adds it as the first child of the selection.Think prependChild.
• canInsertChild: False if selection is a leaf.

Please not that these are empirical findings. I am pretty confident that they are accurate for the mutators, I am pretty sure that they are incomplete for the canXyz methods. In other words, even if canAdd seems to be true all the time, I wouldn't assume that add always succeeds and still bind to canAdd.