Repository: angular
Issue: Forms: State that setErrors() will make status === INVALID regardless of value passed for key
Labels: feature,state: Needs Design,breaking changes,area: forms,feature: under consideration

<!--
PLEASE HELP US PROCESS GITHUB ISSUES FASTER BY PROVIDING THE FOLLOWING INFORMATION.

ISSUES MISSING IMPORTANT INFORMATION MAY BE CLOSED WITHOUT INVESTIGATION.
-->

## I'm submitting a...
<!-- Check one of the following options with "x" -->
<pre><code>
[ ] Regression (a behavior that used to work and stopped working in a new release)
[ ] Bug report  <!-- Please search GitHub for a similar issue or PR before submitting -->
[ ] Feature request
[x] Documentation issue or request
[ ] Support request => Please do not submit support request here, instead see https://github.com/angular/angular/blob/master/CONTRIBUTING.md#question
</code></pre>

## Current behavior
<!-- Describe how the issue manifests. -->
In the `setErrors` example for [AbstractControl ](https://angular.io/api/forms/AbstractControl#setErrors) it shows passing `true` for the key. **The issue is that the control's status will be set to INVALID no matter the value of the key (or even just passing `setErrors` an empty object** [(see _calculateStatus code)](https://github.com/angular/angular/blob/5.2.0/packages/forms/src/model.ts#L561-L635) 
However, as the example is given, it's reasonable to infer that you clear the errors by `setErrors( {"notUnique": false})`, when really you'd need to do `setErrors(null)` or, as the example *does* show, set the control's value to a new value.

````
const login = new FormControl("someLogin");
login.setErrors({
  "notUnique": true
});

expect(login.valid).toEqual(false);
expect(login.errors).toEqual({"notUnique": true});

login.setValue("someOtherLogin");

expect(login.valid).toEqual(true);
````

## Expected behavior
<!-- Describe what the desired behavior would be. -->
Update documentation to explicitly say how to clear errors in code (as this is useful to know when doing integration (template) testing, where you just want to set an error, check the template, then clear the error and check that any alerts have gone away.

## Minimal reproduction of the problem with instructions
<!--
For bug reports please provide the *STEPS TO REPRODUCE* and if possible a *MINIMAL DEMO* of the problem via
https://plnkr.co or similar (you can use this template as a starting point: http://plnkr.co/edit/tpl:AvJOMERrnz94ekVua0u5).
-->
**Failing test**
````
const login = new FormControl("someLogin");
login.setErrors({
  "notUnique": true
});

expect(login.valid).toEqual(false);
expect(login.errors).toEqual({"notUnique": true});

login.setErrors({"notUnique": false});
expect(login.valid).toEqual(true); //will still be INVALID since the check: if(this.errors) will return TRUE
````

**Suggested example**
````
const login = new FormControl("someLogin");
login.setErrors({
  "notUnique": true
});

expect(login.valid).toEqual(false);
expect(login.errors).toEqual({"notUnique": true});

login.setValue("someOtherLogin"); //or: login.setErrors(null); <===add this comment

expect(login.valid).toEqual(true);
````

Alternatively (though this would be code change, not just a documentation change), is that in `_calculateStatus()`, you only set to INVALID if at least one key in the `errors` object is set to `true`.

## What is the motivation / use case for changing the behavior?
<!-- Describe the motivation or the concrete use case. -->
When I am doing integration (template) testing to validate that alert/error messages show up when a control is invalid, and I choose to use the `setErrors()` function to create an INVALID status, I want to know how to then create a VALID status (either by setting a valid value or by passing null to the `control.setErrors()` function.

## Environment

<pre><code>
Angular version: 4.4.1
<!-- Check whether this is still an issue in the most recent Angular version -->

Browser:
- [ ] Chrome (desktop) version XX
- [ ] Chrome (Android) version XX
- [ ] Chrome (iOS) version XX
- [ ] Firefox version XX
- [ ] Safari (desktop) version XX
- [ ] Safari (iOS) version XX
- [ ] IE version XX
- [ ] Edge version XX
 
For Tooling issues:
- Node version: XX  <!-- run `node --version` -->
- Platform:  <!-- Mac, Linux, Windows -->

Others:
<!-- Anything else relevant?  Operating system version, IDE, package manager, HTTP server, ... -->
</code></pre>