diff --git a/core/lib/Drupal/Core/Entity/ContentEntityInterface.php b/core/lib/Drupal/Core/Entity/ContentEntityInterface.php
index fde6af9..e2c22ec 100644
--- a/core/lib/Drupal/Core/Entity/ContentEntityInterface.php
+++ b/core/lib/Drupal/Core/Entity/ContentEntityInterface.php
@@ -42,8 +42,14 @@ public function initTranslation($langcode);
   /**
    * Defines the base fields of the entity type.
    *
-   * Implementations may use the class \Drupal\Core\Field\FieldDefinition for
-   * creating the field definitions.
+   * Implementations typically use the class \Drupal\Core\Field\FieldDefinition
+   * for creating the field definitions; for example a 'name' field could be
+   * defined as the following:
+   * @code
+   * $fields['name'] = FieldDefinition::create()
+   *   ->setLabel(t('Name'))
+   *   ->setFieldType('string');
+   * @endcode
    *
    * @param string $entity_type
    *   The entity type to return properties for. Useful when a single class is
diff --git a/core/lib/Drupal/Core/Field/FieldDefinition.php b/core/lib/Drupal/Core/Field/FieldDefinition.php
index 2c4f5e7..d13d4cc 100644
--- a/core/lib/Drupal/Core/Field/FieldDefinition.php
+++ b/core/lib/Drupal/Core/Field/FieldDefinition.php
@@ -29,7 +29,7 @@ public function getFieldName() {
    * @param string $name
    *   The field name to set.
    *
-   * @return \Drupal\Core\Field\FieldDefinition
+   * @return self
    *   The object itself for chaining.
    */
   public function setFieldName($name) {
@@ -53,7 +53,7 @@ public function getFieldType() {
    * @param string $type
    *   The field type to set.
    *
-   * @return \Drupal\Core\Field\FieldDefinition
+   * @return self
    *   The object itself for chaining.
    */
   public function setFieldType($type) {
@@ -74,7 +74,7 @@ public function getFieldSettings() {
    * @param array $settings
    *   The value to set.
    *
-   * @return \Drupal\Core\Field\FieldDefinition
+   * @return self
    *   The object itself for chaining.
    */
   public function setFieldSettings(array $settings) {
@@ -98,7 +98,7 @@ public function getFieldSetting($setting_name) {
    * @param mixed $value
    *   The value to set.
    *
-   * @return \Drupal\Core\Field\FieldDefinition
+   * @return self
    *   The object itself for chaining.
    */
   public function setFieldSetting($setting_name, $value) {
@@ -127,7 +127,7 @@ public function isFieldTranslatable() {
    * @param bool $translatable
    *   Whether the field is translatable.
    *
-   * @return \Drupal\Core\Field\FieldDefinition
+   * @return self
    *   The object itself for chaining.
    */
   public function setTranslatable($translatable) {
@@ -192,7 +192,7 @@ public function isFieldMultiple() {
    * @param bool $required
    *   Whether the field is required.
    *
-   * @return \Drupal\Core\Field\FieldDefinition
+   * @return self
    *   The object itself for chaining.
    */
   public function setFieldRequired($required) {
@@ -212,7 +212,7 @@ public function isFieldQueryable() {
    * @param bool $queryable
    *   Whether the field is queryable.
    *
-   * @return \Drupal\Core\Field\FieldDefinition
+   * @return self
    *   The object itself for chaining.
    */
   public function setFieldQueryable($queryable) {
@@ -228,7 +228,7 @@ public function setFieldQueryable($queryable) {
    * @param array $constraints
    *   The constraints to set.
    *
-   * @return \Drupal\Core\Field\FieldDefinition
+   * @return selfr
    *   The object itself for chaining.
    */
   public function setPropertyConstraints($name, array $constraints) {
diff --git a/core/lib/Drupal/Core/TypedData/DataDefinition.php b/core/lib/Drupal/Core/TypedData/DataDefinition.php
index de17f46..798a536 100644
--- a/core/lib/Drupal/Core/TypedData/DataDefinition.php
+++ b/core/lib/Drupal/Core/TypedData/DataDefinition.php
@@ -56,7 +56,7 @@ public function getDataType() {
    * @param string $type
    *   The data type to set.
    *
-   * @return \Drupal\Core\TypedData\DataDefinitionInterface
+   * @return self
    *   The object itself for chaining.
    */
   public function setDataType($type) {
@@ -77,7 +77,7 @@ public function getLabel() {
    * @param string $label
    *   The label to set.
    *
-   * @return \Drupal\Core\TypedData\DataDefinition
+   * @return self
    *   The object itself for chaining.
    */
   public function setLabel($label) {
@@ -98,7 +98,7 @@ public function getDescription() {
    * @param string $description
    *   The description to set.
    *
-   * @return \Drupal\Core\TypedData\DataDefinition
+   * @return self
    *   The object itself for chaining.
    */
   public function setDescription($description) {
@@ -127,10 +127,10 @@ public function isReadOnly() {
   /**
    * Sets whether the data is read-only.
    *
-   * @param bool $read-only
+   * @param bool $read_only
    *   Whether the data is read-only.
    *
-   * @return \Drupal\Core\TypedData\DataDefinition
+   * @return self
    *   The object itself for chaining.
    */
   public function setReadOnly($read_only) {
@@ -151,7 +151,7 @@ public function isComputed() {
    * @param bool $computed
    *   Whether the data is computed.
    *
-   * @return \Drupal\Core\TypedData\DataDefinition
+   * @return self
    *   The object itself for chaining.
    */
   public function setComputed($computed) {
@@ -172,7 +172,7 @@ public function isRequired() {
    * @param bool $required
    *   Whether the data is required.
    *
-   * @return \Drupal\Core\TypedData\DataDefinition
+   * @return self
    *   The object itself for chaining.
    */
   public function setRequired($required) {
@@ -193,7 +193,7 @@ public function getClass() {
    * @param string|null $class
    *   The class to use.
    *
-   * @return \Drupal\Core\TypedData\DataDefinition
+   * @return self
    *   The object itself for chaining.
    */
   public function setClass($class) {
@@ -219,7 +219,7 @@ public function getSettings() {
    * @param array $settings
    *   The array of settings.
    *
-   * @return \Drupal\Core\TypedData\DataDefinition
+   * @return self
    *   The object itself for chaining.
    */
   public function setSettings(array $settings) {
@@ -248,7 +248,7 @@ public function getConstraints() {
    * @param array $constraints
    *   The array of constraints.
    *
-   * @return \Drupal\Core\TypedData\DataDefinition
+   * @return self
    *   The object itself for chaining.
    */
   public function setConstraints(array $constraints) {
@@ -266,7 +266,7 @@ public function setConstraints(array $constraints) {
    * @param array|null $options
    *   The constraint options as required by the constraint plugin, or NULL.
    *
-   * @return \Drupal\Core\TypedData\DataDefinition
+   * @return self
    *   The object itself for chaining.
    */
   public function addConstraint($constraint_name, $options = NULL) {