hook_field_info needs docs for 'field item class' key

Good point, and thanks for reporting this! At least, all implementations have this, and it looks like the function field_data_type_info() uses it. We should add that to the hook documentation. Probably a good Novice issue (Drupal 8.x only). It needs to be added to the documentation and to the sample implementation in the function body.

Here you go.

Thanks for the patch! I think it needs some work before it is ready to commit though.

+ *   - field item class: The namespace of the implementing class (i.e. provided
+ *     by the field type module, or by a module the field type module depends on).
 

I don't think that the statement here is accurate. From the examples in the sample function body, it appears to be a fully-namespaced class name, not a namespace. Also, I don't think the i.e. clause is accurate... I think you are trying to say that the class must be a field type class, presumably a class that extends some particular base field type class, but waht is "provided" and "depends on"? It's really important to use the right terminology for class, namespace, extends, etc. in documentation in order for it to be clear and precise.

Also, I would advise against using "i.e." in documentation. We periodically have to go through and fix these up, because people confuse i.e. and e.g. all the time, and it is rarely punctuated correctly (including in this patch). Here, I think it can just be left out entirely.

Thanks for the patch(es)! The latest patch still has a few issues:

a) This change is not grammatically correct:

  *     instances of this field type, when no widget is specified in the instance
  *     definition. This widget must be available whenever the field type is
- *     available (i.e. provided by the field type module, or by a module the
- *     field type module depends on).
+ *     available. Provided by the field type module, or by a module the
+ *     field type module depends on.

"Provided by the..." is not a sentence, and also it's really an explantion of what "whenever the field type is available" means. So, it needs to stay in parentheses; just doesn't need the "i.e.". There is a similar change in the formatter section just below that also needs to be fixed, and the new field item section also has this problem.

b)

+ *     Should be a class that extends Drupal\Core\Entity\Field\FieldItemBase.

In documentation, any time you use a namespace, it needs to start with a \ -- and I'm a bit confused here about the word "Should". Does that really mean "It must be", or "Usually it is"? I suppose the answer is that usually it extends FieldItemBase, and it must implement FieldItemInterface. Let's say that, assuming I'm correct?

c) The interface FieldItemInterface says it's an interface for "field items", so let's make sure we use that terminology in this documentation for 'field item class' -- don't call it the class that "implements the field type", call it the class that implements "defines the field item".

The classes that implement that interface, such as TextFieldItem, say they "define the field item". If this is the wrong terminology, then the documentation of those classes also needs to be changed.

And hook_field_info() defines "field types". It does not define "field items" or "field item types". ... What are field items anyway? Maybe we should define this as well?

I don't know what to say about the terminology. Moving to the Field system so the maintainers can comment.

It is a purely documentation issue, and will not be affected by the API freeze. The component was changed in #13 to field system in hopes that the maintainers of the field system would comment on the terminology.

8.x only has hook_field_info_alter() left, which is an alter hook of the @FieldType annotation, and it's now 'class' and not 'field item class'.

I guess that can be improved too, but would be a completely different patch than it was before, so maybe a new issue would make more sense if we want to improve that? (I'm sure the field API documentation as a while needs some, uhm, fine-tuning after all the changes that happened...)

Yeah, this is an old issue. I don't think we need to worry about it now that there is not a hook_field_info().