docs(isolateScope): unclear usage of element.scope() vs. element.isolateScope()

[gesellix]

According to the docs at http://docs.angularjs.org/guide/scope one can retrieve the isolate scope of a directive by using angular.element(aDomElement).scope().
After 27e9340 being available in Angular 1.2.x there is another way of accessing the isolate scope by using angular.element(aDomElement).isolateScope().

I'm not sure where to add a hint for developers writing unit tests for their directives and trying to access the isolate scope, but I would prefer to at least mention the additional method in the migration guide.

Perhaps a section in the developer guide with focus on unit tests would help or could the function isolateSope() be regarded as common feature and as such be documented in the official guide for scopes?

[caitp]

element.scope() will never return the isolate scope anymore, if this is still present in the documentation, please submit a pull request to fix this! Thanks =)

... however a quick grep of the generated documentation doesn't seem to say that element.scope() will ever give you the isolate scope. So it's probably okay, hmm.

Anyways, I think it's understandably confusing to people, so perhaps it could be improved on in some way just to make the distinction between the two scopes clear.

[gesellix]

The jqLite docs also state that element.isolateScope() doesn't always return a scope, but element.scope() does. As you suggested, there's some need to clear the difference of both scopes and when or not to use one of them.

Would you say that the section "Scope and Directives" is the correct one? I could make a draft and we can discuss it here?

[caitp]

I've left a comment on your patch:

So again, isolateScope() and scope() do different things.

scope() is essentially element.inheritedData('$scope'). inheritedData() means it will crawl up through parent nodes until it finds a scope (it isn't necessarily guaranteed to find one, though, for instance if the application root is not document but some internal node)

isolateScope() does not use inheritedData(), it looks at element.data('$isolateScope') and element.data('$isolateScopeNoTemplate'), which are quite distinct from $scope (isolate scopes are not inherited by children)

I hope that clears it up for you

[gesellix]

If you prefer, we can continue the discussion here, the commit is far from being a pull request

[gesellix]

I would like to add your explanation to the docs, especially the difference between crawling up parent nodes for scope() and accessing element data when using isolateScope().

[gesellix]

The directive guide already mentioned the fact that isolated scopes don't inherit from their parent, so I only added some links and short comments to raise some awareness.
Explaining the different behaviour of Angular with and without crawling up through parent nodes would be an extra section in the scope guide for me. It seems hard to me sharing the explanation in both the scope and the directive guide without copying content.
Your feedback is welcome!