diff --git a/core/modules/comment/comment.tokens.inc b/core/modules/comment/comment.tokens.inc
index 464e266..db6c3cb 100644
--- a/core/modules/comment/comment.tokens.inc
+++ b/core/modules/comment/comment.tokens.inc
@@ -169,7 +169,8 @@ function comment_tokens($type, $tokens, array $data = array(), array $options =
           $replacements[$original] = url('comment/' . $comment->id() . '/edit', $url_options);
           break;
 
-        // @todo remove 'name' token in favour of 'author'.
+        // @todo Remove 'name' token in favour of 'author'. See
+        //   https://drupal.org/node/920056.
         case 'name':
         case 'author':
           $name = $comment->getAuthorName();
diff --git a/core/modules/comment/lib/Drupal/comment/CommentInterface.php b/core/modules/comment/lib/Drupal/comment/CommentInterface.php
index ed0154a..30daa27 100644
--- a/core/modules/comment/lib/Drupal/comment/CommentInterface.php
+++ b/core/modules/comment/lib/Drupal/comment/CommentInterface.php
@@ -26,7 +26,7 @@
   const PUBLISHED = 1;
 
   /**
-   * Determine if this comment is a reply to another comment.
+   * Determines if this comment is a reply to another comment.
    *
    * @return bool
    *   TRUE if the comment has a parent comment otherwise FALSE.
@@ -66,18 +66,19 @@ public function getCommentedEntityId();
   public function getCommentedEntityType();
 
   /**
-   * Returns the ID of the comment field the comment is attached to.
+   * Returns the field ID of the comment field the comment is attached to.
    *
-   * @return int
-   *   The field ID of the field the comment is attached to.
+   * @return string
+   *   The field identifier of the field the comment is attached to.
    */
   public function getFieldId();
 
   /**
-   * Set the field ID for which this commment is attached.
+   * Sets the field ID for which this comment is attached.
    *
    * @param string $field_id
-   *   The field identifier
+   *   The field identifier, usually formatted: {entity_type}__{field_name},
+   *   for example, node__comment.
    *
    * @return \Drupal\comment\CommentInterface
    *   The class instance that this method is called on.
@@ -93,18 +94,18 @@ public function setFieldId($field_id);
   public function getFieldName();
 
   /**
-   * Returns the title of the comment.
+   * Returns the subject of the comment.
    *
    * @return string
-   *   The title of the comment.
+   *   The subject of the comment.
    */
   public function getSubject();
 
   /**
-   * Sets the title of the comment.
+   * Sets the subject of the comment.
    *
    * @param string $subject
-   *   The title of the comment.
+   *   The subject of the comment.
    *
    * @return \Drupal\comment\CommentInterface
    *   The class instance that this method is called on.
@@ -128,10 +129,10 @@ public function getAuthor();
   public function getAuthorId();
 
   /**
-   * Set the comment author by their uid.
+   * Sets the comment author by their user ID.
    *
    * @param int $uid
-   *   The author's unique id.
+   *   The author's unique ID.
    *
    * @return \Drupal\comment\CommentInterface
    *   The class instance that this method is called on.
@@ -269,7 +270,7 @@ public function getThread();
    * Sets the alphadecimal representation of the comment's place in a thread.
    *
    * @param string $thread
-   *   The alphadecimal representation of the comment's place in a thread
+   *   The alphadecimal representation of the comment's place in a thread.
    *
    * @return \Drupal\comment\CommentInterface
    *   The class instance that this method is called on.
diff --git a/core/modules/comment/lib/Drupal/comment/Controller/CommentController.php b/core/modules/comment/lib/Drupal/comment/Controller/CommentController.php
index 3e13ada..643e571 100644
--- a/core/modules/comment/lib/Drupal/comment/Controller/CommentController.php
+++ b/core/modules/comment/lib/Drupal/comment/Controller/CommentController.php
@@ -236,7 +236,7 @@ public function getReplyForm(Request $request, $entity_type, $entity_id, $field_
         }
         // Load the parent comment.
         $comment = $this->entityManager()->getStorageController('comment')->load($pid);
-        // Check if the parent comment is published and belongs to the current nid.
+        // Check if the parent comment is published and belongs to the entity.
         if (!$comment->isPublished() || ($comment->getCommentedEntityId() != $entity->id())) {
           drupal_set_message($this->t('The comment you are replying to does not exist.'), 'error');
           return new RedirectResponse($this->urlGenerator()->generateFromPath($uri['path'], array('absolute' => TRUE)));
diff --git a/core/modules/comment/lib/Drupal/comment/Entity/Comment.php b/core/modules/comment/lib/Drupal/comment/Entity/Comment.php
index 3a059f7..0f77fb9 100644
--- a/core/modules/comment/lib/Drupal/comment/Entity/Comment.php
+++ b/core/modules/comment/lib/Drupal/comment/Entity/Comment.php
@@ -56,8 +56,8 @@
 class Comment extends ContentEntityBase implements CommentInterface {
 
   /**
-    * The thread for which a lock was acquired.
-    */
+   * The thread for which a lock was acquired.
+   */
   protected $threadLock = '';
 
   /**