FormController $setValidity documentation: signature doesn't match implementation signature

[fixermark]

I'm submitting a ...

• [ x ] bug report

Current behavior:

Documentation for $setValidity shows its signature as

$setValidity();

Implementation actually takes three arguments: the validation error key, the state to set the key to, and a "controller" third argument that (based on how it's used) appears to be the controller for the edit form.

Expected / new behavior:

Please update documentation to match implementation. A code snippet would also help to clarify the meaning of the arguments.

Angular version: master branch

[gkalpak]

I was about to update the docs, when I realized I don't know any good usecase for this method. It updates the validity on a form (and parent forms), but without affecting the control.

Has anyone used this or has ideas on how this could be useful?

[frederikprijck]

@gkalpak Could it be that this issue is about what you're saying? #13202

The issue is mentioning it's not doing anything with the controls/childs. Looks like the same as you're saying. Looks like the usecases for the method (using the current implementation) are limited, however I'd say having a form.$setValidity(), resetting all controls, isn't bad. (but it has been missing untill today, so I guess it's not something people need).

[Narretz]

We should probably update the docs regardless of any considerations about setting child form validity. The whole form / model API is messy in this regard.
What's the 3rd argument anyway? The parent controller?

It looks like this function is only useful in propagating the state of a control (ngModel) to its parent form(s). A form method that sets the validity of its controls (and its child forms and so on) must probably be a new function. Or could be implemented by exposing the child forms / controls: #14749

[gkalpak]

What's the 3rd argument anyway? The parent controller?

It is the child controller (the one that has/had the error).

It looks like this function is only useful in propagating the state of a control (ngModel) to its parent form(s).

Not sure what you mean. This function is for updating the error/validity of a form (based on that of a child controller; NgModelController or FormController) and propagate that upwards (e.g. in parent FormControllers). Just to be clear, we are talking about FormController#$setValidity(), not NgModelController#$setValidity(). (The latter one is properly documented.)

TBH, I only see this being useful for internal use (i.e. to be called from the control's $setValidity method in order to propagate the error/validity upwards). I can't think of another, external usecase (but maybe I am missing something).

[Narretz]

Not sure what you mean.

I think we mean the same. $setValidity is usually called when a child control (ngModel) changes validity and informs the parent form.

We still can add the info that this is a function for internal use (as it has been exposed in the API for a long time)

[gkalpak]

Yeah, we probably mean the same. (But I would like to point out that there are two different $setValidity methods, even if they are created using the same helper and thus share a big part of their implementation. 😛)

OOC, @fixermark do you have a usecase for FormController#$setValidity()? Were you trying to use it? What for?

[fixermark]

We have a situation where we are using a directive to modify the validity of a form element, and as a side-effect of checking the validity of that element, we also need to modify the validity of a second element that determines its validity based on the value of the first element.