clarify directive documentation on using literals in the directive html attribute

[jcaxmacher]

Let's say I want to pass a string literal into a directive. I can do that one of two ways:

<div v-example-directive="'test'">Message</div>

The literal string test will show up as the value parameter to my directive's bind method. However, the need for single quotes inside the double quotes is a bit of an eyesore. So, we could do it this way:

<div v-example-directive="test">Message</div>

The literal string test is then available as this.key in my directive's methods. I like the way this looks better, but it has the potential to be confusing. The directive documentation needs to be good enough for me to know if it will interpret the keypath as a string or if a literal string expression is needed.

Additionally, are there consequences (performance or otherwise) to abusing this.key for literal strings?

I think these questions should be addressed in the directives in depth section of the documentation. The list of directives in the API reference does a good job of calling out "literal" directives, but they are not split up in the list at the top of the page.

[yyx990803]

Agreed. I once had a isLiteral option when you create directives. But now the implementation is like this: since literal directives do not need data binding capabilities, they don't need an update method. So if your directive definition does not provide an update method, all data binding work will be skipped (which essentially makes it a literal directive by using this.key). There is no bad consequences here. In fact you should avoid using quotes for literal values because that makes the directive an expression and requires a lot more internal work to evaluate it.

I will clarify this in the docs better. Thanks.

[bpierre]

isFn should also be documented.

[yyx990803]

moving this to the vuejs.org repo.