[webkit-dev] Rename of selfOnlyRef to guardRef - ok if I change it back? (was Re: DOM tree traversal on detached nodes)

[Maciej Stachowiak]

On Jun 15, 2012, at 10:31 AM, Darin Adler <darin at apple.com> wrote:

> On Jun 15, 2012, at 10:15 AM, Maciej Stachowiak <mjs at apple.com> wrote:
> 
>> But it's hard to explain fully in a function name w/o excess verbosity.
> 
> I think my favorite excess verbosity version is refDocumentButNotOtherNodes.

Things I dislike about that one:

- Seems to imply that normal ref() refs other nodes, which it doesn't really (though it does act as a refcount controlling whether the document will possibly remove its children while still alive)
- Extremely vague about which other nodes, to the point of giving the implication that ref() might ref completely arbitrary other nodes. Or else it gives the impression that it's just the right ref to use on Document but not on other classes.
- No obvious sensible name for the corresponding refcount data member (m_refDocumentButNotOtherNodesCount does not seem clear to me).

The way I'd fully explain the design is as follows:

- Document has two refcounts, the normal refcount and the self-only refcount.
- The document will not be destroyed so long as either refcount is nonzero.
- If the normal refcount is zero but the self-only refcount is zero, the document will remove all of its own children.
- Descendant nodes of the document should hold a self-only ref to their owner document, not a regular ref, to avoid reference cycles.

I am not sure how to get the key points across without being accurate or misleading. A version that I think explains the complete design without saying anything false or misleading:

refTheDocumentItselfButUnlikeTheRegularRefDontPreventTheDocumentsChildrenFromBeingRemovedToAvoidCyclesWhenRefingTheOwnerDocument

To make a reasonable name we probably need to focus on one of these aspects. Perhaps one approach is to focus on when and why you should use this call, rather than what it does:

refAsOwnerDocument() / m_refCountAsOwnerDocument (or m_ownerDocumentRefCount)
refAvoidingCycles() (or cycleAvoidingRef()) / m_cycleAvoidingRefCount

Regards,
Maciej