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

previous topic  Previous:  Code Analyzers Support Next:  Jindent Plugins   next topic

title

6 Comment Switches


Sometimes it can be useful to supress Jindent's formatting of certain source code elements. For this case Jindent provides three special Java comments which disable and enable Jindent. These kind of comments are called Comment Switches.
For a clear input these comments should appear in a single line.



//J+ and //J- Comments


Use comment switch //J- to leave original code untouched and use //J+ to make Jindent taking up its formatting again.


For example the source code input:

    class Demo                          
    {                                   
//J-                                    
        int                             
        sillyStyle1(int x)   // This style will be kept
          {                             
            x += 2; return x;           
          }                             
//J+                                    
        int                             
        sillyStyle2(int y)              
          {                             
            y += 2; return y;           
          }                             
    }                                   

would look after formatting:

    class Demo {                        
                                        
//J-                                    
        int                             
        sillyStyle1(int x)   // This style will be kept
          {                             
            x += 2; return x;           
          }                             
//J+                                    
        int sillyStyle2(int y) {        
            y += 2;                     
                                        
            return y;                   
        }                               
    }                                   

The source code between //J- and //J+ is not formatted and keeps the style from the original input source code.


This option can be very useful to keep the original style of complicated array definitions.
To avoid mistakes or missing insertions the comment switch //J+ should follow after each //J-.



//JDOC- Comment


Comment switch //JDOC- can be used to suppress automatical JavaDoc insertion.


We assume Jindent is configured to insert JavaDocs before classes.
Now Jindent is supposed to format the following two classes:

public class Test {                     
                                        
    /**                                 
     * Some text ...                    
     *                                  
     * @param input    input string     
     *                                  
     * @throws Exception    if anything went wrong 
     */                                 
    public void run(String input) throws Exception {
                                        
        // do something                 
                                        
        ...                             
    }                                   
}                                       
                                        
public class ExtendedTest extends Test {
                                        
    public void run(String input) throws Exception {
                                        
        // do something more            
                                        
        ...                             
    }                                   
                                        
    ...                                 
}                                       


After formatting and insertion JavaDocs the same source code looks like:

/**                                     
 * New inserted JavaDoc                 
 *                                      
 *                                      
 * @author ...                          
 */                                     
public class Test {                     
                                        
    /**                                 
     * Some text ...                    
     *                                  
     * @param input    input string     
     *                                  
     * @throws Exception    if anything went wrong 
     */                                 
    public void run(String input) throws Exception {
                                        
        // do something                 
                                        
        ...                             
    }                                   
}                                       
                                        
/**                                     
 * New inserted JavaDoc                 
 *                                      
 *                                      
 * @author ...                          
 */                                     
public class ExtendedTest extends Test {
                                        
    /**                                 
     * New inserted JavaDoc             
     *                                  
     * @param input ...                 
     *                                  
     * @throws Exception ...            
     */                                 
    public void run(String input) throws Exception {
                                        
        // do something more            
                                        
        ...                             
    }                                   
                                        
    ...                                 
}                                       


Since the JavaDoc tool from Sun supports inheritance of JavaDoc comments the insertion for method ExtendedTest.run(String) is unwanted. We rather would like to get no insertion at this place. Therefore we keep the inherited JavaDoc comment from method Test.run(String).
To understand the inheritance correcly Jindent would need to parse all Java files in a whole project context. This would slow down Jindent's formatting process too much though.

But we can use the comment switch //JDOC- to tell Jindent not to insert any JavaDoc comment at this place.


Our example source code would now look like:

public class Test {                     
                                        
    /**                                 
     * Some text ...                    
     *                                  
     * @param input    input string     
     *                                  
     * @throws Exception    if anything went wrong 
     */                                 
    public void run(String input) throws Exception {
                                        
        // do something                 
                                        
        ...                             
    }                                   
}                                       
                                        
public class ExtendedTest extends Test {
                                        
    //JDOC-                             
    public void run(String input) throws Exception {
                                        
        // do something more            
                                        
        ...                             
    }                                   
                                        
    ...                                 
}                                       
Now no unnecessary JavaDoc template will be inserted for method ExtendedTest.run(String) and the JavaDoc inheritance will be kept.