Document why some attribute directive are dash-case and some are camelCase

Bug, feature request, or proposal:

Currently there is a confusion as to why mdInput is an attribute directive [which is the reason why it is written as mdInput instead of md-input] & md-button is a component

Since md-button(and other button variants) are used only as html attributes, it would be easy for the user’s mental model if he can write

<button mdButton> instead of <button md-button> similar to <input mdInput>

What is the expected behavior?

Ability to use button variations using camelCase such as <button mdButton>

What is the current behavior?

All button variations needs to be used using kabab cased attribute <button md-button>

What is the use-case or motivation for changing an existing behavior?

Now the user needs to know how button is implemented (which is why it is kabab case instead of camel), instead end user should not care how it is implemented, instead just knows elements follow kabab case & directives follow camelCase.

This way, the implementation detail does not leak to end user

The mental model of “html element => component”, “html attribute => directive” is easy to remember & intuitive for most angular developers.

Which versions of Angular, Material, OS, browsers are affected?

2.0.0-beta.2

[jelbourn]

The current behavior is that @Components are dash-case and @Directives are camelCase. The reasoning is that an element can only have one @Component, but multiple @Directive instances. So you can tell by looking at <button mat-button matTooltip="Hello"> that MatButton is the @Component, and all of the unprefixed attributes (disabled, color, disableRipple, etc.) apply to that, while MatTooltip is a directive and its properties would all be prefixed with matTooltip

[thw0rted]

Just came from #18606. I think confusion arose there because the docs agree with @jelbourn, telling you to use camelCase directives, but the example for the same components shows the directives in dash-case (<mat-icon mat-list-icon>folder</mat-icon>).

Would it make sense to resolve this issue by reviewing the docs to ensure that both the Overview and Example tabs of each component consistently use these case conventions?