Jindent - Java Source Code Formatter http://www.jindent.com
 

previous topic  Previous:  Chunks Next:  Deleting   next topic

title
5.6.1.11 Comments

title
5.6.1.11.1 Formatting

Format block comments

Format block comments

Enables formatting of block comments.

Block comments are from type /* ... */ and contain muliple comment lines.
To preserve block comment style from original source code just disable this setting.


Do not format block comments and and an example could look like:

/*                                      
   unformatted                          
   block                                
   comment                              
 */                                     


Format block comments and the same example looks like:

/*                                      
 * unformatted                          
 * block                                
 * comment                              
 */                                     

See also... See also: Blank lines before block comments , Blank lines after block comments , Delete block comments




Format single-line comments

Format single-line comments

Enables formatting of single-line comments.

Single-line comments are from type /* ... */ and only contain one comment line.
To preserve single-line comment style from original source code just disable this setting.


Do not format single-line comments and and an example could look like:

/*unformatted comment*/                 


Format single-line comments and the same example looks like:

/* unformatted comment */               

See also... See also: Blank lines before single-line comments , Blank lines after single-line comments , Delete single-line comments




Format end-of-line comments

Format end-of-line comments

Enables formatting of end-of-line comments.

End-of-line comments are from type // ... and do not appear as trailing comments.
To preserve end-of-line comment style from original source code just disable this setting.


Do not format single line comments and an example could look like:

int a = 0;                              
//unformatted end of line comment       
callMethod(a);                          


Format end-of-line comments and the same example looks like:

int a = 0;                              
// unformatted end of line comment      
callMethod(a);                          

See also... See also: Blank lines before end-of-line comments , Blank lines after end-of-line Comments , Delete end-of-line comments




Format trailing comments

Format trailing comments

Enables formatting of trailing comments.

Trailing comments are all kind of comments which appear on the same line as the code they describe. They are placed at the end of a line.
To preserve trailing comment style from original source code just disable this setting.


Do not format single line comments and and an example could look like:

int a = 0;        //unformatted trailing comment
callMethod(a);    /*another unformatted trailing comment*/


Format end-of-line comments and the same example looks like:

int a = 0;        // unformatted trailing comment
callMethod(a);    /* another unformatted trailing comment */

See also... See also: Delete trailing comments




Do NOT format comments containing keys

Do NOT format comments containing keys

Sometimes it is necessary to skip formatting for comments generated by documentation tools, GUI designers or any other tools. Changing the comment formatting could irritate the tool's parser and in the worst case the tool would loose its assistance to the generated comment.

Jindent offers a setting to define exception rules to skip formatting for such kind of comments.
Just define specific (comma separated) unique keys which appear in the comments you would like to skip and Jindent will be able to leave these comments unformatted.



Let's assume that no exception rule is defined and all comment formatting settings are enabled. A source code sample would now be formatted like:

/*                                      
 * modification history                 
 * --------------------                 
 * 2010-03-01 added new exception handling
 * 2010-01-21 fixed bug 23412           
 * 2009-12-10 fixed bug 13459           
 * ...                                  
 */                                     
public class MyClass                    
{                                       
   /* some other block comments here */ 
   ...                                  
}                                       
In this case all comments are formatted even if the original "modification history" comment looked like:

/*                                      
 modification history                   
 --------------------                   
 2010-03-01 added new exception handling
 2010-01-21 fixed bug 23412             
 2009-12-10 fixed bug 13459             
 ...                                    
 */                                     
If the documentation tool which created the "modification history" comment contains a very strict comment parser then it will not be able to understand the new formatted comment anymore.

Now the same code sample but this time we define an exception rule for the word modification history and the new output looks like:

/*                                      
 modification history                   
 --------------------                   
 2010-03-01 added new exception handling
 2010-01-21 fixed bug 23412             
 2009-12-10 fixed bug 13459             
 ...                                    
 */                                     
public class MyClass                    
{                                       
   /* some other block comments here */ 
   ...                                  
}                                       
Now Jindent skips formatting of the first "modification history" comment and the documentation tool will still be able to recognize its created comment.
All other comments which do not contain the word "modification history" will be formatted as usual of course.


Never indent and format comments beginning in first column

Never indent and format comments beginning in first column

Disables formatting and indentation of comments which start in the first column of source code.

First column comments are usually commented out source code elements which begin in the first column.


Do not change first column comments and and an example could look like:

public class MyClass                    
{                                       
                                        
    public void method() {              
/*                                      
      long i = 0;                       
      while (i < n) {                   
         result *= i;                   
         i++;                           
      }                                 
*/                                      
                                        
      doSomethingElse();                
   }                                    
}                                       


Allow indentation and formatting of first column comments and the previous example would look like:

public class MyClass                    
{                                       
                                        
    public void method() {              
      /*                                
       *    long i = 0;                 
       *    while (i < n) {             
       *       result *= i;             
       *       i++;                     
       *    }                           
       */                               
                                        
      doSomethingElse();                
   }                                    
}                                       

This 'destroys' formatting and indentation of commented out source code elements.
For that reason setting "Never indent and format comments beginning in first column" can be used to protect commented out source code.



Indent comment out source code in first column comments

Indent comment out source code in first column comments

Indents content of first column comments to current block indentation.


We assume the following input source code:

public class MyClass                    
{                                       
                                        
    public void calc() {                
                                        
        long result = 0;                
                                        
//  long i = 0;                         
//  while (i < n) {                     
//     result *= i;                     
//     i++;                             
//  }                                   
                                        
        result = doSomethingElse();     
        ...                             
    }                                   
}                                       

In this example the commented out source code does not fit to the current indentation level of method calc().


Enabling setting: "Indent comment out source code in first column comments" automatically indents the content of first column comments to its correct block indentation level:

public class MyClass                    
{                                       
                                        
    public void calc() {                
                                        
        long result = 0;                
                                        
//      long i = 0;                     
//      while (i < n) {                 
//         result *= i;                 
//         i++;                         
//      }                               
                                        
        result = doSomethingElse();     
        ...                             
    }                                   
}