.bind and .to docs are unclear

[tomalec]

📝 Provide a description of requested docs changes

...at least to me. After reading

• https://ckeditor.com/docs/ckeditor5/latest/framework/guides/deep-dive/observables.html#property-bindings and
• https://ckeditor.com/docs/ckeditor5/latest/api/module_utils_observablemixin-ObservableMixin.html#function-bind

I still am not sure how do those two work.

1. Does A.bind( 'propFoo' ).to( B, 'propBar') binds one way or both ways?
2. Is it just a sugar layer for the code below?

   B.on( 'change:propBar', (e, p, newValue) => A.set( 'propFoo', newValue )}

3. Where are the docs for to and toMany? https://ckeditor.com/docs/ckeditor5/latest/framework/guides/deep-dive/observables.html#property-bindings says:

   Returns Object The bind chain with the to() and toMany() methods.

   No links and there is nothing I can find neither for "bind chain", "to", nor "toMany". (Besides, https://ckeditor.com/docs/ckeditor5/latest/api/module_ui_template-BindChain.html which probably is unrelated and just confusing).

   Browsing through the code is hard for a keyword like "to", https://github.com/ckeditor/ckeditor5-utils/blob/master/src/observablemixin.js#L369-L372 still gives me only a circular reference and no clue ;)

4. When the callback is called? - When any value changes? When any setter is called even with the same value? When some event is triggered regardless of the value?
5. Can I use the callback for a single property to "translate" the value? Like: A.bind( 'initial' ).to( B, 'name', (name) => name[0])

[CKEditorBot]

There has been no activity on this issue for the past year. We've marked it as stale and will close it in 30 days. We understand it may still be relevant, so if you're interested in the solution, leave a comment or reaction under this issue.