API References should be painfully explicit about two-way binding.

[jrood]

Currently, in the API references, there are @Input and @Output listed in such a way that seems to take for granted that the reader knows that if there exists an @Input called x and an @Output called xChange that you should be able to use the banana-in-a-box [(x)] syntax to do a two way binding. I imagine this is a touchy subject because some will feel that this is obvious, and yet I've been using Angular 2 for a number of months and it was not at all clear to me, even though I've used that syntax with [(ngModel)] plenty of times.

On the API reference for tabs, it says selectedIndexChange was added to allow for two way binding. I'm sure some people will read that and think "that's abundantly clear", and indeed for some experienced Angular 2 developers, that probably does obviously imply that you can expect to use [(selectedIndex)], but I think for other readers it's not so obvious.

This library is advertised on the angular.io page, which makes me think the target audience is just as much novice Angular 2 developers as it is experienced ones. Since this is the case, I think API references should err on the side of being painfully explicit. It should not merely be said that 'two-way binding' is enabled, but explicitly that [(thisSyntax)] can be used.

[M-a-c]

@jrood Since there are a lot of components how would you suggest doing this?
Just adding a * next to everything that can use two way binding then linking to a special page about it? or putting a example of two way binding in each component?

[jroodHNTB]

Thanks @M-a-c , I was imagining an example in each component.

[M-a-c]

@jroodHNTB so would that show every @input method you could do, or just explain how it is useful and leave the rest up to the user?

[jrood]

(sorry for switching between jrood and jroodHNTB accounts)
@M-a-c It looks to me like the API docs already are listing every @input method (as well as every @output method) under the 'Properties' section for each component. What I'm thinking is: since we are already listing every one-way binding, we should also list every two way binding.

[M-a-c]

For the button component is there even anything that can be two way bound?
I'm just looking for an example of a component that does do two way binding.
Could you give me an example? I'm a bit ignorant on the subject. I know how it works, and I have a lot of time this and next week to contribute.

https://material.angular.io/components/component/button
https://github.com/angular/material2/blob/master/src/lib/button/button.ts

[jrood]

It doesn't look like there is anything on a button that can be two way bound. An example on Tabs under MdTabGroup is that there is an input selectedIndex which you could use like this <md-tab-group [selectedIndex]="someValueOrVariable"> and an output selectedIndexChange which you could use like this <md-tab-group (selectedIndexChange)="someMethod()">. What I think should be added is an entry that says: by the way, you can access both at the same time like this <md-tab-group [(selectedIndex)]="someVariable">

[M-a-c]

@jrood so that does say "Output to enable support for two-way binding on selectedIndex."
but you explicitly state that two way binding is implemented ([like])="this"
How exactly did you have in mind though. so it lists the @input,@output would you like it to have and additional ([twoWaybinding]) = "variable".

Also I am trying to think of how best to implement this. I'm trying to avoid the use of gulp if possible.
I mean the way the API page is created is with gulp reading through the JsDoc, so..
Not sure exactly how we're going to do what you're suggesting easily. But i get what you're saying now.

How exactly do you envision it looking?

[jrood]

Hmm, now that I'm thinking more about this, it might not be necessary to add a new line, but just to actually use the syntax in the explanation "Output to enable support for two-way binding via [(selectedIndex)]" .

For the two-way binding syntax, square braces are always on the outside and parenthesis on the inside like this [()], thus the phrase 'banana in a box'.

They're using gulp to build the docs? Hmm I don't know if I can help you with that.

[M-a-c]

@jrood Also two way binding is available for any input that has set of get set methods right?

should the two way binding be mentioned on just the output or also the input ?
I wonder what @kara thinks.

[jrood]

@M-a-c Unfortunately get and set methods do not imply two-way binding, they might just be used internally within the component.

I don't have a strong opinion about whether it's on both. Just the output is probably fine.

[M-a-c]

So how can you say for sure if something is two way bound?
Ps (we can handle this on my fork) M-a-c#1

[jrood]

It has to have an @input and then an @output that has the same name as the @input plus 'Change'. So you could have an @input called 'salmongrass' and an @output called 'salmongrassChange', and that would mean you could use the two-way binding syntax [(salmongrass)]="someVariable". I sort of initially inferred that information, and then latter confirmed it in reading this article https://blog.thoughtram.io/angular/2016/10/13/two-way-data-binding-in-angular-2.html

[M-a-c]

so I looked through the components and core.. All I could find was MdTabGroup with two way binding, that's seriously the only component with two way binding that i could find.