Issue #1480866 by hansyg, underq, Berdir, tstoeckler, cosmicdreams: Add...

Issue #1480866 by hansyg, underq, Berdir, tstoeckler, cosmicdreams: Add type-hinting and parameter type documentation for comment objects.

core/modules/comment/comment.admin.inc

@@ -264,7 +264,7 @@ function comment_confirm_delete_page($cid) {
 /**
  * Form constructor for the confirmation form for comment deletion.
  *
- * @param $comment
+ * @param Comment $comment
  *   The comment that is about to be deleted.
  *
  * @ingroup forms
@@ -272,7 +272,7 @@ function comment_confirm_delete_page($cid) {
  * @see comment_confirm_delete_submit()
  * @see confirm_form()
  */
-function comment_confirm_delete($form, &$form_state, $comment) {
+function comment_confirm_delete($form, &$form_state, Comment $comment) {
   $form['#comment'] = $comment;
   // Always provide entity id in the same form key as in the entity edit form.
   $form['cid'] = array('#type' => 'value', '#value' => $comment->cid);

core/modules/comment/comment.api.php

@@ -16,10 +16,10 @@
  * This hook is invoked from comment_save() before the comment is saved to the
  * database.
  *
- * @param $comment
+ * @param Comment $comment
  *   The comment object.
  */
-function hook_comment_presave($comment) {
+function hook_comment_presave(Comment $comment) {
   // Remove leading & trailing spaces from the comment subject.
   $comment->subject = trim($comment->subject);
 }
@@ -27,10 +27,10 @@ function hook_comment_presave($comment) {
 /**
  * Respond to creation of a new comment.
  *
- * @param $comment
+ * @param Comment $comment
  *   The comment object.
  */
-function hook_comment_insert($comment) {
+function hook_comment_insert(Comment $comment) {
   // Reindex the node when comments are added.
   search_touch_node($comment->nid);
 }
@@ -38,10 +38,10 @@ function hook_comment_insert($comment) {
 /**
  * Respond to updates to a comment.
  *
- * @param $comment
+ * @param Comment $comment
  *   The comment object.
  */
-function hook_comment_update($comment) {
+function hook_comment_update(Comment $comment) {
   // Reindex the node when comments are updated.
   search_touch_node($comment->nid);
 }
@@ -49,10 +49,10 @@ function hook_comment_update($comment) {
 /**
  * Act on comments being loaded from the database.
  *
- * @param $comments
+ * @param array $comments
  *  An array of comment objects indexed by cid.
  */
-function hook_comment_load($comments) {
+function hook_comment_load(Comment $comments) {
   $result = db_query('SELECT cid, foo FROM {mytable} WHERE cid IN (:cids)', array(':cids' => array_keys($comments)));
   foreach ($result as $record) {
     $comments[$record->cid]->foo = $record->foo;
@@ -62,7 +62,7 @@ function hook_comment_load($comments) {
 /**
  * Act on a comment that is being assembled before rendering.
  *
- * @param $comment
+ * @param Comment $comment
  *   Passes in the comment the action is being performed on.
  * @param $view_mode
  *   View mode, e.g. 'full', 'teaser'...
@@ -71,7 +71,7 @@ function hook_comment_load($comments) {
  *
  * @see hook_entity_view()
  */
-function hook_comment_view($comment, $view_mode, $langcode) {
+function hook_comment_view(Comment $comment, $view_mode, $langcode) {
   // how old is the comment
   $comment->time_ago = time() - $comment->changed;
 }
@@ -108,20 +108,20 @@ function hook_comment_view_alter(&$build) {
 /**
  * Respond to a comment being published by a moderator.
  *
- * @param $comment
+ * @param Comment $comment
  *   The comment the action is being performed on.
  */
-function hook_comment_publish($comment) {
+function hook_comment_publish(Comment $comment) {
   drupal_set_message(t('Comment: @subject has been published', array('@subject' => $comment->subject)));
 }
 
 /**
  * Respond to a comment being unpublished by a moderator.
  *
- * @param $comment
+ * @param Comment $comment
  *   The comment the action is being performed on.
  */
-function hook_comment_unpublish($comment) {
+function hook_comment_unpublish(Comment $comment) {
   drupal_set_message(t('Comment: @subject has been unpublished', array('@subject' => $comment->subject)));
 }
 
@@ -132,14 +132,14 @@ function hook_comment_unpublish($comment) {
  * field_attach_delete() is called and before the comment is actually removed
  * from the database.
  *
- * @param $comment
+ * @param Comment $comment
  *   The comment object for the comment that is about to be deleted.
  *
  * @see hook_comment_delete()
  * @see comment_delete_multiple()
  * @see entity_delete_multiple()
  */
-function hook_comment_predelete($comment) {
+function hook_comment_predelete(Comment $comment) {
   // Delete a record associated with the comment in a custom table.
   db_delete('example_comment_table')
     ->condition('cid', $comment->cid)
@@ -153,14 +153,14 @@ function hook_comment_predelete($comment) {
  * field_attach_delete() has called and after the comment has been removed from
  * the database.
  *
- * @param $comment
+ * @param Comment $comment
  *   The comment object for the comment that has been deleted.
  *
  * @see hook_comment_predelete()
  * @see comment_delete_multiple()
  * @see entity_delete_multiple()
  */
-function hook_comment_delete($comment) {
+function hook_comment_delete(Comment $comment) {
   drupal_set_message(t('Comment: @subject has been deleted', array('@subject' => $comment->subject)));
 }
 

core/modules/comment/comment.module

@@ -164,7 +164,7 @@ function comment_node_type_load($name) {
 /**
  * Entity uri callback.
  */
-function comment_uri($comment) {
+function comment_uri(Comment $comment) {
   return array(
     'path' => 'comment/' . $comment->cid,
     'options' => array('fragment' => 'comment-' . $comment->cid),
@@ -934,7 +934,7 @@ function comment_prepare_thread(&$comments) {
 /**
  * Generates an array for rendering a comment.
  *
- * @param $comment
+ * @param Comment $comment
  *   The comment object.
  * @param $node
  *   The node the comment is attached to.
@@ -947,7 +947,7 @@ function comment_prepare_thread(&$comments) {
  * @return
  *   An array as expected by drupal_render().
  */
-function comment_view($comment, $node, $view_mode = 'full', $langcode = NULL) {
+function comment_view(Comment $comment, $node, $view_mode = 'full', $langcode = NULL) {
   if (!isset($langcode)) {
     $langcode = $GLOBALS['language_content']->langcode;
   }
@@ -1004,7 +1004,7 @@ function comment_view($comment, $node, $view_mode = 'full', $langcode = NULL) {
  * The content built for the comment (field values, comments, file attachments
  * or other comment components) will vary depending on the $view_mode parameter.
  *
- * @param $comment
+ * @param Comment $comment
  *   A comment object.
  * @param $node
  *   The node the comment is attached to.
@@ -1014,7 +1014,7 @@ function comment_view($comment, $node, $view_mode = 'full', $langcode = NULL) {
  *   (optional) A language code to use for rendering. Defaults to the global
  *   content language of the current request.
  */
-function comment_build_content($comment, $node, $view_mode = 'full', $langcode = NULL) {
+function comment_build_content(Comment $comment, $node, $view_mode = 'full', $langcode = NULL) {
   if (!isset($langcode)) {
     $langcode = $GLOBALS['language_content']->langcode;
   }
@@ -1048,7 +1048,7 @@ function comment_build_content($comment, $node, $view_mode = 'full', $langcode =
 /**
  * Adds reply, edit, delete, etc. links, depending on user permissions.
  *
- * @param $comment
+ * @param Comment $comment
  *   The comment object.
  * @param $node
  *   The node the comment is attached to.
@@ -1056,7 +1056,7 @@ function comment_build_content($comment, $node, $view_mode = 'full', $langcode =
  * @return
  *   A structured array of links.
  */
-function comment_links($comment, $node) {
+function comment_links(Comment $comment, $node) {
   $links = array();
   if ($node->comment == COMMENT_NODE_OPEN) {
     if (user_access('administer comments') && user_access('post comments')) {
@@ -1450,13 +1450,13 @@ function comment_user_predelete($account) {
  * @param $op
  *   The operation that is to be performed on the comment. Only 'edit' is
  *   recognized now.
- * @param $comment
+ * @param Comment $comment
  *   The comment object.
  *
  * @return
  *   TRUE if the current user has acces to the comment, FALSE otherwise.
  */
-function comment_access($op, $comment) {
+function comment_access($op, Comment $comment) {
   global $user;
 
   if ($op == 'edit') {
@@ -1467,10 +1467,10 @@ function comment_access($op, $comment) {
 /**
  * Accepts a submission of new or changed comment content.
  *
- * @param $comment
+ * @param Comment $comment
  *   A comment object.
  */
-function comment_save($comment) {
+function comment_save(Comment $comment) {
   $comment->save();
 }
 
@@ -1643,12 +1643,12 @@ function comment_get_display_page($cid, $node_type) {
 /**
  * Page callback: Displays the comment editing form.
  *
- * @param $comment
+ * @param Comment $comment
  *   The comment object representing the comment to be edited.
  *
  * @see comment_menu()
  */
-function comment_edit_page($comment) {
+function comment_edit_page(Comment $comment) {
   drupal_set_title(t('Edit comment %comment', array('%comment' => $comment->subject)), PASS_THROUGH);
   $node = node_load($comment->nid);
   return drupal_get_form("comment_node_{$node->type}_form", $comment);
@@ -1673,7 +1673,7 @@ function comment_forms() {
  * @see comment_form_build_preview()
  * @ingroup forms
  */
-function comment_form($form, &$form_state, $comment) {
+function comment_form($form, &$form_state, Comment $comment) {
   global $user, $language_content;
 
   // During initial form build, add the comment entity to the form state for
@@ -1887,9 +1887,11 @@ function comment_form_build_preview($form, &$form_state) {
 /**
  * Generates a comment preview.
  *
+ * @param Comment $comment
+ *
  * @see comment_form_build_preview()
  */
-function comment_preview($comment) {
+function comment_preview(Comment $comment) {
   global $user;
 
   drupal_set_title(t('Preview comment'), PASS_THROUGH);
@@ -1986,8 +1988,11 @@ function comment_form_validate($form, &$form_state) {
 
 /**
  * Prepare a comment for submission.
+ *
+ * @param Comment $comment
+ *
  */
-function comment_submit($comment) {
+function comment_submit(Comment $comment) {
   if (empty($comment->date)) {
     $comment->date = 'now';
   }
@@ -2327,15 +2332,15 @@ function comment_action_info() {
 /**
  * Publishes a comment.
  *
- * @param $comment
- *   An optional comment object.
+ * @param Comment $comment
+ *   (optional) A comment object to publish.
  * @param array $context
  *   Array with components:
  *   - 'cid': Comment ID. Required if $comment is not given.
  *
  * @ingroup actions
  */
-function comment_publish_action($comment, $context = array()) {
+function comment_publish_action(Comment $comment = NULL, $context = array()) {
   if (isset($comment->subject)) {
     $subject = $comment->subject;
     $comment->status = COMMENT_PUBLISHED;
@@ -2354,15 +2359,15 @@ function comment_publish_action($comment, $context = array()) {
 /**
  * Unpublishes a comment.
  *
- * @param $comment
- *   An optional comment object.
+ * @param Comment|null $comment
+ *   (optional) A comment object to unpublish.
  * @param array $context
  *   Array with components:
  *   - 'cid': Comment ID. Required if $comment is not given.
  *
  * @ingroup actions
  */
-function comment_unpublish_action($comment, $context = array()) {
+function comment_unpublish_action(Comment $comment = NULL, $context = array()) {
   if (isset($comment->subject)) {
     $subject = $comment->subject;
     $comment->status = COMMENT_NOT_PUBLISHED;
@@ -2381,7 +2386,7 @@ function comment_unpublish_action($comment, $context = array()) {
 /**
  * Unpublishes a comment if it contains certain keywords.
  *
- * @param $comment
+ * @param Comment $comment
  *   Comment object to modify.
  * @param array $context
  *   Array with components:
@@ -2392,7 +2397,7 @@ function comment_unpublish_action($comment, $context = array()) {
  * @see comment_unpublish_by_keyword_action_form()
  * @see comment_unpublish_by_keyword_action_submit()
  */
-function comment_unpublish_by_keyword_action($comment, $context) {
+function comment_unpublish_by_keyword_action(Comment $comment, $context) {
   foreach ($context['keywords'] as $keyword) {
     $text = drupal_render($comment);
     if (strpos($text, $keyword) !== FALSE) {
@@ -2433,9 +2438,11 @@ function comment_unpublish_by_keyword_action_submit($form, $form_state) {
 /**
  * Saves a comment.
  *
+ * @param Comment $comment
+ *
  * @ingroup actions
  */
-function comment_save_action($comment) {
+function comment_save_action(Comment $comment) {
   comment_save($comment);
   cache_clear_all();
   watchdog('action', 'Saved comment %title', array('%title' => $comment->subject));

core/modules/comment/comment.pages.inc

@@ -47,12 +47,9 @@ function comment_reply($node, $pid = NULL) {
     // $pid indicates that this is a reply to a comment.
     if ($pid) {
       if (user_access('access comments')) {
-        // Load the comment whose cid = $pid
-        $comment = db_query('SELECT c.*, u.uid, u.name AS registered_name, u.signature, u.signature_format, u.picture, u.data FROM {comment} c INNER JOIN {users} u ON c.uid = u.uid WHERE c.cid = :cid AND c.status = :status', array(
-          ':cid' => $pid,
-          ':status' => COMMENT_PUBLISHED,
-        ))->fetchObject();
-        if ($comment) {
+        // Load the parent comment.
+        $comment = comment_load($pid);
+        if ($comment->status = COMMENT_PUBLISHED) {
           // If that comment exists, make sure that the current comment and the
           // parent comment both belong to the same parent node.
           if ($comment->nid != $node->nid) {

core/modules/comment/comment.test

@@ -96,7 +96,7 @@ class CommentHelperCase extends DrupalWebTestCase {
   /**
    * Checks current page for specified comment.
    *
-   * @param object $comment
+   * @param Comment $comment
    *   The comment object.
    * @param boolean $reply
    *   Boolean indicating whether the comment is a reply to another comment.
@@ -104,8 +104,8 @@ class CommentHelperCase extends DrupalWebTestCase {
    * @return boolean
    *   Boolean indicating whether the comment was found.
    */
-  function commentExists($comment, $reply = FALSE) {
-    if ($comment && is_object($comment)) {
+  function commentExists(Comment $comment = NULL, $reply = FALSE) {
+    if ($comment) {
       $regex = '/' . ($reply ? '<div class="indented">(.*?)' : '');
       $regex .= '<a id="comment-' . $comment->id . '"(.*?)'; // Comment anchor.
       $regex .= '<div(.*?)'; // Begin in comment div.
@@ -123,10 +123,10 @@ class CommentHelperCase extends DrupalWebTestCase {
   /**
    * Deletes a comment.
    *
-   * @param object $comment
+   * @param Comment $comment
    *   Comment to delete.
    */
-  function deleteComment($comment) {
+  function deleteComment(Comment $comment) {
     $this->drupalPost('comment/' . $comment->id . '/delete', array(), t('Delete'));
     $this->assertText(t('The comment and all its replies have been deleted.'), t('Comment deleted.'));
   }