Documentation for FileRepositoryInterface::writeData() says it creates a file entity, but it can update existing

Problem/Motivation

The docblock for Drupal\file\FileRepositoryInterface::writeData() has this line:
Writes a file to the specified destination and creates a file entity.

However, the implementation in Drupal\file\FileRepository::writeData() calls Drupal\file\FileRepository::createOrUpdate(), where if there is an existing file entity matching the URI where the file data is saved on disk, the file is loaded and saved, and no new file entity is created.

The documentation then is misleading.

Steps to reproduce

Proposed resolution

Update the docblock in Drupal\file\FileRepositoryInterface::writeData() to indicate it will either update a matching file entity or create a new file entity.

Remaining tasks

User interface changes

Introduced terminology

API changes

Data model changes

Release notes snippet