How to add description like: "Comments for paragraph 1" to comments I have written a module that allows users to put comment on each paragraph. So in comment form there is a field that asks the user which paragraph do they want to put comment on. 
I have to mention that I have added a column to my comment table, which saves that paragraph number. 

function Annotations_form_comment_form_alter(&amp;$form, &amp;$form_state, $form_id) {
$form['paragraph_id'] = array(
    '#type' =&gt; 'textfield',
    '#title' =&gt; t('Which paragraph you want to put comment on?'),
    '#required' =&gt; TRUE,
    '#size' =&gt; 10,
    '#maxlength' =&gt; 2,
    '#default_value' =&gt; !empty($form['#entity']-&gt;paragraph_id) ? $form['#entity']-   &gt;paragraph_id : NULL, // set the default value to the current paragraph value
     '#weight' =&gt; $form['subject']['#weight'] + 1, // place after the subject   field by setting the weight to +1 of subject weight
);

$form['#validate'][] = 'annotations_form_comment_form_validate';
$form['#submit'][] = 'annotations_form_comment_form_submit';

 }


I also have Annotations_form_comment_form_validate  and Annotations_form_comment_form_submit functions for validation and submitting.

I have also written the following code to sort the comments based on the number of the paragraph. So first you see the comments on paragraph 1, and then 2, etc.

    &lt;?php

  define('COMMENT_SORT_OLDER_FIRST', 1); // default
  define('COMMENT_SORT_Paragraph', 2);
 /* Alter node type form: allow user to decide comments sorting */
  function Annotations_form_node_type_form_alter(&amp;$form, $form_state) {
  $form['comment']['comment_default_sorting'] = array(
 '#title' =&gt; t('Sort'),
 '#type' =&gt; 'select',
 '#options' =&gt; array(1 =&gt; t('Older first'), 
                     2 =&gt; t('Paragraph Number')),
 '#default_value' =&gt; variable_get('comment_default_sorting_' . $form['#node_type']-&gt;type, COMMENT_SORT_OLDER_FIRST), 
 );
  }


  /* Alter comments query */
 function Annotations_query_comment_filter_alter(QueryAlterableInterface $query){
  if ( ($node = $query-&gt;getMetaData('node')) &amp;&amp; (get_class($query) == 'PagerDefault')             ) {
  $sort = variable_get('comment_default_sorting_' . $node-&gt;type,              COMMENT_SORT_OLDER_FIRST);
    if ($sort == COMMENT_SORT_Paragraph) {
  $orderby =&amp; $query-&gt;getOrderBy();  
  $expressions =&amp; $query-&gt;getExpressions();
  if (isset($orderby['torder'])) { 
      unset($expressions['torder']);
      unset($orderby['torder']);
      $orderby['c.paragraph_id'] = 'ASC';
  } else {
    $orderby['c.cid'] = 'DESC';
    }
   }
 }
}


I want to have a line like: " Comments on Paragraph 1 " and then show the comments for paragraph 1, and the same for rest of the comments. 

Does anybody know how can I do that  or which hooks I can use? Do you know some other modules or examples that do something similar, so it will give me some idea that how to do it?
I don't think it will really be answerable without the code you wrote. 

General answer is:


alter query that gets comments to include paragraph number (hook_query_alter)
alter their rendering, so paragraph number is sent to .tpl files (hook_comment_view_alter)
change tpl file of your theme to display that number.