ToggleCommentAction

Version: 0.1 Draft

This is a functional specification of the behaviour of toggle comment action (TCA). The action is supposed to do comment or uncomment of certain part of the code based on user action.

The specification covers the behaviour of TCA for single language, no embedded cases are solved (so far).

A basic implementation has been created in csl.api module. See org.netbeans.modules.csl.spi.CommentHandler class for more information. The implementation is not embedding aware, so far the TCA always use the top level language comment.

An extension of this specification for the embedded environment is TBD.

TCA Examples

The code part below the delimiter is the code state before TCA execution, the code below after. The pipe characters denotes selection or caret position.

Commenting

Comment of clean selection

The code doesn't contain any comments neither inside nor around the selection.

|h1 {
    color: red;
}|
-----
|/*h1 {
    color: red;
}*/|


Comment of code with comments

The selection contains another comments - these embedded delimiters are deleted and one big comment for the whole selection is created. The main idea of the determination whether to do comment of uncomment is the beginning selection. If the selection starts in normal code then comment is done, otherwise uncomment is done.

|h1 {
    /* color: red; */
}|
-----
|/*h1 {
    color: red;
}*/|

Comment of code abuting with a comment

Comment are not joined, new separate comment is created.

h1 {
   /*color: red;*/|
}|
-----
h1 {
   /*color: red;*/|/*
}*/

Uncommenting

Uncomment of clean selection

The selection contains just comment with delimiters.

|/*h1 {
    color: red;
}*/|
-----
|h1 {
    color: red;
}|

Uncomment of part of comment

The selection starts with comment and ends at or after the end of the comment.

h1 {
   /* co|lor: red; */
}|
-----
h1 {
   /* co*/|lor: red; 
}|

Uncomment inside comment

The selection starts and ends inside a comment.

h1 {
   /* co|lor: r|ed; */
}|
-----
h1 {
   /* co*/|lor: r|/*ed; */ 
}

Other

Language unit sensitivity

The TCA is not language context sensitive so if you select a part of a language syntax unit and do TCA, the exactly selected part will be un/commented, no additional selection adjustments are done. The user may use Select code action to make a language syntax unit selection.

No selection

If no selection is done the TCA behaviour is like the whole line with caret is selected. An example a comment behaves like this:

h1 {
   color: |red;
}
-----
h1 {
   /* color: |red; */ 
}

or uncomment like this:

h1 {
   /* color: |red; */ 
}
-----
h1 {
   color: |red;
}

The decision wheater to comment or uncomment the line is done at caret position and not at the line beginning. For example:

h1 {
   /*color:*/ |red;
}
-----
h1 {
   /* color: |red; */ 
}

or uncomment like this:

h1 {
   /* color:|*/ red; */ 
}
-----
h1 {
   color:| red;
}


Empty line

If no selection is done and the line is empty (contains just whitespaces) the TCA does nothing.

Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo