diff --git a/core/modules/comment/comment.api.php b/core/modules/comment/comment.api.php
index 078401e..551f030 100644
--- a/core/modules/comment/comment.api.php
+++ b/core/modules/comment/comment.api.php
@@ -141,7 +141,9 @@ function hook_comment_view_alter(&$build, \Drupal\comment\Entity\Comment $commen
  * Respond to a comment being published by a moderator.
  *
  * @param Drupal\comment\Comment $comment
- *   The comment the action is being performed on.
+ *   This hook is invoked every time a comment is saved and 
+ *   changes the status of the comment to published,
+ *   whether it was previously in a published status or not.
  */
 function hook_comment_publish(Drupal\comment\Comment $comment) {
   drupal_set_message(t('Comment: @subject has been published', array('@subject' => $comment->subject->value)));
@@ -151,7 +153,9 @@ function hook_comment_publish(Drupal\comment\Comment $comment) {
  * Respond to a comment being unpublished by a moderator.
  *
  * @param Drupal\comment\Comment $comment
- *   The comment the action is being performed on.
+ *   This hook is invoked every time a comment is saved and 
+ *   changes the status of the comment to unpublished,
+ *   whether it was previously in a unpublished status or not.
  */
 function hook_comment_unpublish(Drupal\comment\Comment $comment) {
   drupal_set_message(t('Comment: @subject has been unpublished', array('@subject' => $comment->subject->value)));