template (Directive Def Object) description in $compile docs

[Izhaki]

The docs (source) for template state:

replace the current element with the contents of the HTML.

Let's do this bit by bit.

replace the current element

First, shouldn't 'current element' change to 'the element on which the directive is declared'.

Then:

For the following element:

<my-directive>Original</my-directive>

This directive:

myApp.directive( 'myDirective', function() {
    return {
        restrict: 'E',
        template: 'New'
    }
});

Will result in:

<my-directive>New</my-directive>

So the current element isn't replaced at all (<my-directive>..</my-directive> is still there).

What am I missing here?

contents of the HTML

Which contents?

Isn't contents what's between tags? As in:

<tag>contents</tag>

And which HTML?

Shouldn't it read:

Replaces the contents of the element on which the directive is declared with the markup provided in the template property.

Also:

The replacement process migrates all of the attributes / classes from the old element to the new one. See the Directives Guide for an example.

I don't really understand this and I couldn't find anything on the Directives Guide.

It really seems that the text applies more to the (deprecated) replace property, rather than template.

[caitp]

replace the current element with the contents of the HTML. The replacement process
migrates all of the attributes / classes from the old element to the new one. See the
Directives Guide for an example.

This looks like it was actually moved from the documentation of the replace property.

If replace is truthy, then The replacement process migrates all of the attributes / classes from the old element to the new one. is correct, however this does not occur otherwise. In the non-replace scenario, the element isn't replaced, but the template content replaces any child nodes (needless to say, this doesn't work for comment directives).

In either case, the original child nodes of the "current element" (that is to say, from the compilers perspective, the current element on the stack being compiled) are removed --- but they can be compiled if the transclude flag is set to a non-falsy, non-'element' value.

The directive API is ridiculous, nobody is arguing that, but I hope that explains a little bit. @btford I think we should probably do a better job with that paragraph, because it really looks like it's describing replace rather than template.

[Izhaki]

Thanks @caitp. All you say is correct and known. Perhaps I should have emphasised that I think the docs should change.

There are so many issues with the docs - it's such a shame. Sometimes, it seems the terminology picked is very very ambiguous. How can one contribute to making things right? I'm not authoritative enough to fork and propose doc pull requests. Shall I report an issue for everything I see?

There's another, momentous (I believe) doc issue I believe should be addressed. I'll create a new issue and raise it to your attention.

[caitp]

I agree that the docs should change, heh =) You're welcome to write a PR for this

[btford]

@Izhaki – I'm catching up after a long weekend. I agree that we can do better here. Thanks for your help!