diff -u b/core/lib/Drupal/Core/Entity/Field/FieldDefinitionInterface.php b/core/lib/Drupal/Core/Entity/Field/FieldDefinitionInterface.php
--- b/core/lib/Drupal/Core/Entity/Field/FieldDefinitionInterface.php
+++ b/core/lib/Drupal/Core/Entity/Field/FieldDefinitionInterface.php
@@ -8,19 +8,134 @@
 namespace Drupal\Core\Entity\Field;
 
 /**
- * @todo Document
+ * Defines an interface for entity field definitions.
+ *
+ * An entity field is a data object that holds the values of a particular field
+ * for a particular entity (see \Drupal\Core\Entity\Field\FieldInterface). For
+ * example, $node_1->body and $node_2->body contain different data and therefore
+ * are different field objects.
+ *
+ * In contrast, an entity field *definition* is an object that returns
+ * information *about* a field (e.g., its type and settings) rather than its
+ * values. As such, if all the information about $node_1->body and $node_2->body
+ * is the same, then the same field definition object can be used to describe
+ * both.
+ *
+ * Fields can be defined entirely via code, entirely via UI configuration, or
+ * via a combination. Also, some field definitions can be relatively static
+ * while others can vary for each request based on runtime context.  Therefore,
+ * different classes can implement this interface, based on the needs of the
+ * field.
  */
 interface FieldDefinitionInterface {
 
+  /**
+   * Returns the machine name of the field.
+   *
+   * This defines how the field data is accessed from the entity. For example,
+   * if the field name is "foo", then $entity->foo returns its data.
+   *
+   * @return string
+   *   The field name.
+   */
   public function getFieldName();
+
+  /**
+   * Returns the field type.
+   *
+   * Field types are defined by modules that implement hook_field_info().
+   *
+   * @return string
+   *   The field type.
+   */
   public function getFieldType();
+
+  /**
+   * Returns the field settings.
+   *
+   * Each field type defines the settings that are meaningful for that type.
+   * For example, a text field can define a 'max_length' setting, and an image
+   * field can define a 'alt_field_required' setting.
+   *
+   * @return array
+   *   An array of key/value pairs.
+   */
   public function getFieldSettings();
+
+  /**
+   * Returns the value of a given field setting.
+   *
+   * @param string $setting_name
+   *   The setting name.
+   *
+   * @return mixed
+   *   The setting value.
+   */
   public function getFieldSetting($setting_name);
+
+  /**
+   * Returns the names of the field's subproperties.
+   *
+   * A field is a list of items, and each item can contain one or more
+   * properties. All items for a given field contain the same property names,
+   * but the values can be different for each item.
+   *
+   * For example, an email field might just contain a single 'value' property,
+   * while a link field might contain 'title' and 'url' properties, and a text
+   * field might contain 'value', 'summary', and 'format' properties.
+   *
+   * @return array
+   *   The property names.
+   */
   public function getFieldPropertyNames();
+
+  /**
+   * Returns whether the field is translatable.
+   *
+   * @return bool
+   *   TRUE if the field is translatable.
+   */
   public function isFieldTranslatable();
+
+  /**
+   * Returns the human-readable label for the field.
+   *
+   * @return string
+   *   The field label.
+   */
   public function getFieldLabel();
+
+  /**
+   * Returns the human-readable description for the field.
+   *
+   * This is displayed in addition to the label in places where additional
+   * descriptive information is helpful. For example, as help text below the
+   * form element in entity edit forms.
+   *
+   * @return string
+   *   The field description.
+   */
   public function getFieldDescription();
+
+  /**
+   * Returns the maximum number of items allowed for the field.
+   *
+   * Possible values are positive integers or FIELD_CARDINALITY_UNLIMITED.
+   *
+   * @return integer
+   *   The field cardinality.
+   */
   public function getFieldCardinality();
+
+  /**
+   * Returns whether at least one non-empty item is required for this field.
+   *
+   * Currently, required-ness is only enforced at the Form API level in entity
+   * edit forms, not during direct API saves.
+   *
+   * @var bool
+   *   TRUE if the field is required.
+   */
   public function isFieldRequired();
 
 }