Custom form handler's submitForm not called when using example in documentation

Problem/Motivation

The example on the API documentation for form API does not work as a new developer might expect, in that submitForm() is never actually called, given the form API array defined in buildForm(). The form is just reloaded as if it were a GET rather than a POST request.

As far as I can tell, this seems to be because the form builder ignores form submissions if there is no element with '#type' => 'submit' in the form API array. The button doesn't need to be clicked as such; it just needs to be present. When I add a second element to the buildForm() return value, then submitForm() is called fine.

Note that examples.module includes a submit element, so that example works fine.

Proposed resolution

Whether or not the current behaviour of Form API is correct, is not within the scope of this issue.

Instead, this issue only covers changing the documentation must be changed so that the example is the simplest that works, and is also not so simple that it wouldn't be a typical use case (it's rare to find forms without submit buttons nowadays, and such forms might have UX and accessibility issues anyway.)

(Edited after discussion in comments.)

Remaining tasks

1. Work out whether the behaviour I've seen is repeatable.
2. If so, work out how custom form handlers/the form builder ought to work, and then decide whether documentation or code needs fixing.
3. Provide a patch to the documentation.
4. Approve the patch.

User interface changes

None.

API changes

None.

Data model changes

None.