$compile documentation improvement

[djfd]

Hi,

could you pls add to a transclude function description an explicit statement that cloned element passed into cloneAttachFn is compiled but not yet linked (neither pre-, nor post-)?

(that is in practice we get a fresh clone of template)

It seems be not very clear, as least for me, from the current docs. Or am I wrong?

thanks

[gkalpak]

I guess it is not 100% clear, but the following quotes from the docs are strong hints:

The contents are compiled and provided to the directive as a transclusion function.

(It says "compiled"; doesn't mention anything about linking.)

This transclusion function is a special linking function that will return the compiled contents linked to a new transclusion scope.

Again not 100% clear, but since transcludeFn is a linking function and cloneFn is run as part of transcludeFn, it is fair to assume that clone will not be linked inside cloneFn.

When you call a transclusion function you can pass in a clone attach function. This function accepts two parameters, function(clone, scope) { ... }, where the clone is a fresh compiled copy of your transcluded content and the scope is the newly created transclusion scope, to which the clone is bound.

It explicitly says clone is a compiled (not linked) copy, but the last phrase ruins it again: "to which the clone is bound" 😄

What it meant to say (I guess) is: "which the clone will be linked to"

I will make this small change, but if you feel there is any way to improve docs further, feel free to submit a PR (and be our hero 😄).

Transclusion is one of the complex aspects fo directives (which in turn is one of the complex aspects of Angular), so... Yet we still love them both, because thay are amazingly powerful at the same time 😁

In any case, thx for bringing this to our attention, @djfd 👍

[djfd]

yeah, thank you, that is better!

and you are right, there is all required information in the documentation for a careful readers ))

But for a beginners (and "by diagonal" readers) like me it is important to get learning curve as much as possible short and smooth, so clear statements are certainly help. And not every one has English as a mother tongue.

check this, just search for a 'this is compiled but not linked yet', it is in bold, as it is actually important. And it was an insight for me, to be honest ))

[gkalpak]

Tbh, "transclusion with custom cloneAttachFn" is a pretty advanced topic. Beginners (or diagonal readers) will have a hard time no matter how much bold we add 😄

_{But maybe adding a similar comment in our example is not a bad idea anyway - PRs welcome if anyone feels like it}

[djfd]

thanks, it is too late to became a hero, I was born with SVN in my hands, so git learning is out of my scope ))