Mark field_create_*(), field_update_*() and field_delete_*() deprecated in favor of just using the ConfigEntity API

+++ b/core/modules/field/field.api.php
@@ -153,8 +153,9 @@ function hook_field_extra_fields_alter(&$info) {
  *   - no_ui: (optional) A boolean specifying that users should not be allowed
  *     to create fields and instances of this field type through the UI. Such
- *     fields can only be created programmatically with field_create_field()
- *     and field_create_instance(). Defaults to FALSE.
+ *     fields can only be created programmatically with
+ *     entity_create('field_entity') and entity_create('field_instance').
+ *     Defaults to FALSE.

That's actually not correct. Such fields and instances can be created by the default configuration of modules, which is actually the preferred way. I have *no* idea how to phrase that, though. :-)

+++ b/core/modules/field/field.api.php
@@ -229,8 +230,8 @@ function hook_field_info_alter(&$info) {
  *   - indexes: (optional) An array of Schema API index definitions. Only
  *     columns that appear in the 'columns' array are allowed. Those indexes
- *     will be used as default indexes. Callers of field_create_field() can
- *     specify additional indexes or, at their own risk, modify the default
+ *     will be used as default indexes. Callers of entity_create('field_entity')
+ *     can specify additional indexes or, at their own risk, modify the default
  *     indexes specified by the field-type module. Some storage engines might
  *     not support indexes.

Same issue here: I think it would be safer to simply say: "When creating a field, additional indexes can be specified or the default indexes can be modified." (and somehow bring the "risk" part into the mix)

+++ b/core/modules/field/field.api.php
@@ -534,7 +535,7 @@ function hook_field_update(\Drupal\Core\Entity\EntityInterface $entity, $field,
+ * This is invoked on the field's storage module from update of field entity,

This should be "... when updating the field entity."

+++ b/core/modules/field/field.api.php
@@ -1626,7 +1627,7 @@ function hook_field_storage_query($query) {
+ * This hook is invoked from field entity creation to ask the field storage

@@ -1644,7 +1645,7 @@ function hook_field_storage_create_field($field) {
+ * This hook is invoked from deletion of field entity to ask the field storage

@@ -1671,7 +1672,7 @@ function hook_field_storage_delete_field($field) {
+ * This hook is invoked from deletion of field instance to ask the field storage

@@ -1885,8 +1886,8 @@ function hook_field_widget_properties_ENTITY_TYPE_alter(array &$widget_propertie
+ * This hook is invoked from field entity creation after the field is created,

I would phrase this as "... is invoked during the [creation|deletion] of a field [instance] entity to ask ..."

I wouldn't bother for now since we're going to delete them anyway :)

Hmm, right, good point, I'll have a look at noon.

+++ b/core/modules/field/field.api.phpundefined
@@ -153,8 +153,9 @@ function hook_field_extra_fields_alter(&$info) {
+ *     fields can only be created programmatically with

Yeah, just remove

'fields can only be created programmatically with field_create_field() and field_create_instance().

+++ b/core/modules/field/field.api.phpundefined
@@ -229,8 +230,8 @@ function hook_field_info_alter(&$info) {
+ *     will be used as default indexes. Callers of entity_create('field_entity')

Additional indexes can be specified, at own risk, which modify the default indexes ..

+++ b/core/modules/field/field.api.phpundefined
@@ -1951,7 +1952,7 @@ function hook_field_update_forbid($field, $prior_field, $has_data) {
+ * This hook is invoked just after field entity is updated.

I'd leave out 'entity', just 'field is updated' is enough imo. Same with other comments when 'entity' is used.

A couple fixes.

  *   - no_ui: (optional) A boolean specifying that users should not be allowed
- *     to create fields and instances of this field type through the UI. Such
- *     fields can only be created programmatically with field_create_field()
- *     and field_create_instance(). Defaults to FALSE.

Why not keep "Such fields can only be created programmatically." ?

+ *     will be used as default indexes. Additional indexes can be specified or,
+ *     at their own risk, modify the default indexes specified by the field-type
+ *     module. Some storage engines might not support indexes.

Nut fully clear IMO, and "their" is blurry.
Proposal:
"Individual field definitions can specify additional indexes or modify, at their own risk, the default indexes specified for the field type. Some storage engines might not support indexes."

+ Wow, the phpdocs for hook_field_[CUD]_(field|instance)() have grown very inconsistent over time.
I know we want to get rid of those eventually, but at least bringing some sanity.

+ Fixed a couple typos / 80 chars / missing words.

Sweet!

Nicer title for the commit log

Committed/pushed to 8.x, thanks!