Cross field validation does not work using "validators" key but works with "validator"

I’m submitting a…

[ ] Regression (a behavior that used to work and stopped working in a new release)
[ ] Bug report  
[ ] Performance issue
[ ] 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
[ ] Other... Please describe:

Current behavior

Following the documentation on Reactive Form and cross field validation (https://angular.io/guide/form-validation#adding-to-reactive-forms-1), I implemented a custom validator to compare if 2 fields are equal. It does work with the following:

// app/shared/validators/confirmation.validator.ts
import { FormGroup, ValidatorFn, ValidationErrors } from '@angular/forms';

export const confirmationValidator = (field1: string, field2: string): ValidatorFn => {
  return (control: FormGroup): ValidationErrors | null => {
    const first  = control.get(field1);
    const second = control.get(field2);

    if (first && second && first.value !== second.value) {
      second.setErrors({ confirmation: true });
      return null;
    }

    second.setErrors({ confirmation: null });
    second.updateValueAndValidity({ onlySelf: true });

    return null;
  };
};

// app/users/user-form.component.ts
private buildForm() {
  this.form = this.fb.group({
    user: this.fb.group({
      id:        [this.user.id],
      lastname:  [this.user.lastname],
      firstname: [this.user.firstname],
      password:  [null, [Validators.minLength(8)]],
      password_confirmation: [null]
    }, { validator: confirmationValidator('password', 'password_confirmation') })
  });
}

Expected behavior

In the example of the documentation (https://angular.io/guide/form-validation#adding-to-reactive-forms-1), they are using the key validators (plural form) but when I do use plural form, my validator is never being called. However, when using singular form (validator) like in my implementation, the validator is being called. In the code, I’ve found a reference to validator (singular form) => https://github.com/angular/angular/blob/6.1.x/packages/forms/src/form_builder.ts#L41

Minimal reproduction of the problem with instructions

Just play by switching from validators to validator as key to define custom validators.

What is the motivation / use case for changing the behavior?

Just want to understand if this is a documentation issue or if I did somehting wrong. Tried to check the doc, it is currently for Angular 6.1.8 but couldn’t find anywhere a change related to that (did I miss something ?). Also, I don’t see a way to check the documentation for a specific Angular version. Is there ?

Environment

Angular version: 6.1.7


Browser:
- [x] Chrome (desktop) version 69.0.3497.100
- [ ] 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: 8.11.4
- Platform:  MacOS Mojave

Others:

[dawidgarus]

There is inconsistency in naming: https://angular.io/api/forms/AbstractControlOptions#properties https://angular.io/api/forms/FormBuilder#group The FormControl requires plural form and FormBuilder singular, but both can be either single validator or array of validators.

[bene-we]

This took me nearly 3 hours!! I used validator (singular), but after changing it to validators (plural) using a FormBuilder it is working now …