text
2 | 3 |More text
4 | 5 | -------------------------------------------------------------------------------- /test/expected/html/quoted.html: -------------------------------------------------------------------------------- 1 | 12.1.6 Comments 2 | Comments must have the following format: 3 | 4 | The string "", or "--!>", nor end with the string "". 7 | 8 | The text is allowed to end with the string " 17 | 18 | 4.6 Block comments 19 | Block comments are typically found within functions, between 'chunks' of code. They also appear in other parts of code, for example at the start of chunks of data. There are a number of common approaches to block comments, several of which are discussed below. 20 | 21 | 4.6.1 Comment size 22 | There are about three different classifications of block comment, depending on its size: 23 | 24 | A single line comment will commonly describe a simple item. 25 | A multiple line comment, up to about 5 lines will summarize a more complex item or set of items. 26 | A longer comment will describe even more, although this is now tending towards a major header comment. 27 | Generally, it must be remembered that a block comment has a cost in vertical space and should give value for money. For example, it may be overkill for a block comment to be bigger than the chunk of function code that it describes. 28 | 29 | 4.6.2 Positioning the comment 30 | A block comment usually describes code below it. This association can be made clearer by using some method to explicitly associate it more closely with the code that it describes. 31 | 32 | Using blank lines 33 | A simple principle is to use a blank line above the comment to physically place it closer to the line below than the line above: 34 | 35 | 36 | 37 | ResetParms(); 38 | 39 | 40 | for ( Win = 0; Win < NofWins; Win++ ) 41 | CloseWin( Win ); 42 | 43 | 44 | 45 | This, however, causes a possible problem where the comment and the code are not immediately distiguishable. A solution, at the cost of more vertical space, is to put a blank line below the comment: 46 | 47 | 48 | 49 | ResetParms(); 50 | 51 | 52 | 53 | for ( Win = 0; Win < NofWins; Win++ ) 54 | CloseWin( Win ); 55 | 56 | 57 | 58 | Indenting the comment 59 | A common method of positioning is to vertically align the comment with the current indent level. This helps to associate the comment with the code below, and preserves the line of indentation. However, this reduces the amount of horizontal space available for comment, particularly at deeper levels of nesting, and may make it more difficult to distinguish between comments and code: 60 | 61 | 62 | 63 | ResetParms(); 64 | 65 | 66 | for ( Win = 0; Win < NofWins; Win++ ) 67 | CloseWin( Win ); 68 | 69 | 70 | 71 | 4.6.3 Enclosing the comment 72 | When block comments cover multiple lines, it is only necessary to use the opening and closing comment tokens. This, however, can result in the limits of the comment becoming less than immediately obvious: 73 | 74 | 75 | 76 | 77 | 78 | 79 | CheckNodes( DB_Nodes ); 80 | 81 | 82 | 83 | A simple principle that can be used in most cases to clarify the limits of multi-line comments, is to put the closing '*/' directly under the opening '*/' (in a similar manner to braces). 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | CheckNodes( DB_Nodes ); 92 | 93 | 94 | 95 | However, reading each line from the left, it is still not immediately clear which line is a comment and which line is not, particularly if the comment is long, and contains blank lines. 96 | 97 | Enclosing from the left 98 | In the previous example, you can clearly delimit the comment one line at a time by making the first character that is read an asterisk. This is using the principle of explicitness to say each time, "This is a comment. It is not code." 99 | 100 | 101 | 102 | 103 | 104 | 105 | 106 | CheckNodes( DB_Nodes ); 107 | 108 | 109 | 110 | There are several common variant on this, such as putting the opening '/*' on a line by itself, thus ensuring an almost-blank line before the comment and enabling easier line insertion after it. Also, the asterisk may be always put in column two or two asterisks can be used on text lines, to emphasize the comment and to be tidy in having two comment characters per line. Some horizontal space can be saved by using spaces instead of tabs to separate the text from the asterisk: 111 | 112 | 113 | 114 | 115 | 116 | 117 | 118 | 119 | CheckNodes( DB_Nodes ); 120 | 121 | 122 | 123 | 124 | 125 | 126 | 127 | Enclosing from above 128 | An alternative or an addition to white space as a method of distinguishing comments from code is to put a bar above the comment, but not below it. This dissociates the comment from the code above, whilst emphasizing its association with the code below. 129 | 130 | 131 | 132 | 133 | 134 | 135 | 136 | 137 | CheckNodes( DB_Nodes ); 138 | 139 | 140 | 141 | Enclosing from below 142 | The comment can be dissociated more from the code below by putting a bar below it too. It is being tidy to keep it the same length as the top line. The dissociation can be further emphasized with a blank line between the comment and the code: 143 | 144 | 145 | 146 | 147 | 148 | 149 | 150 | 151 | 152 | CheckNodes( DB_Nodes ); 153 | 154 | 155 | 156 | Note that the final '*/' is no longer below the opening '/*'. This is not so important as the limits of the comment block are very clear, although there is a danger of missing the final '/', resulting in the code below being commented out. 157 | 158 | A status comment, which describes the code above it, can be enclosed at the bottom, but not the top, to emphasize its association. 159 | 160 | 161 | 162 | 163 | 164 | 165 | 166 | 167 | 168 | 169 | 170 | Enclosing from the right 171 | The final step is now to tidily fill in the right hand side of the box, although this may be considered to be more trouble than it is worth, as it makes editing the comment text less easy. 172 | 173 | 174 | 175 | 176 | 177 | 178 | 179 | 180 | 181 | 182 | 183 | A simplification of the rules about where to place the '/*' and '*/' tokens is to insist that all comments should have matching tokens on the same line. Thus all comment lines are automatically enclosed from the right and the left. 184 | 185 | 186 | 187 | 188 | 189 | 190 | 191 | 192 | 193 | 194 | 195 | With this rule, enclosure from the top and bottom may still be optional. The right hand margin may stay justified or may collapse to a ragged right margin, which eases editing but is not as tidy: 196 | 197 | 198 | 199 | 200 | 201 | 202 | 203 | 204 | 205 | 4.6.4 Delimiters 206 | Comments need not be used for text comments: they may also be used to separate out distinct pieces of code. 207 | 208 | Separating chunks 209 | Drawing lines across the page not only separates the code from the comment, but also separates individual chunks of code, making the chunks easier to see and understand. As these are effectively single-line block comments, they can include simple comments: 210 | 211 | 212 | 213 | 214 | 215 | for ( FileNo = 0; FileNo < NofFilesOpen; FileNo++ ) 216 | { 217 | ErrNo = CloseFile( FileHandle[FileNo] ); 218 | if ( ErrNo != 0 ) 219 | { 220 | FileError( ErrNo ); 221 | } 222 | } 223 | 224 | 225 | 226 | printf( "System closing down,\n" ); 227 | printf( "Remove all tapes and secure in safe.\n"); 228 | 229 | 230 | ... 231 | 232 | 233 | 234 | Multi-line block comments can also a similar scheme, whereby the text in the line is an effective summary for the comment block. 235 | 236 | 237 | 238 | 239 | 240 | 241 | 242 | 243 | ----------------------------------------------------------------------> 244 | 245 | Data/Code delimiters 246 | It can be difficult to immediately find the beginning of the code at the start of a function. For example, a reader might miss the first statement (which may be mistaken for a data declaration). 247 | 248 | 249 | 250 | int 251 | ReadDoorStatus( S_DOOR *Door ) 252 | 253 | { 254 | int DoorType; 255 | int LockType; 256 | DoorType = WOOD; 257 | 258 | LockType = Door->Lock; <------ reader may read code from here! 259 | 260 | 261 | 262 | However, if we put a line across at the start of the data and code sections, no mistakes may be made, and the start of the data and code sections can instantly be found. 263 | 264 | 265 | 266 | int 267 | ReadDoorStatus( S_DOOR *Door ) 268 | 269 | { 270 | 271 | 272 | int DoorType; 273 | int LockType; 274 | 275 | 276 | 277 | DoorType = WOOD; 278 | LockType = Door->Lock; 279 | 280 | 281 | 282 | Delimiter 'weight' 283 | The 'weight' of the delimiter can be used to indicate importance of the section of code or data that is being delimited. The symbols used may be for single line delimiters, or to bound multi-line comment blocks. 284 | 285 | A simple scheme would be: 286 | 287 | Asterisks () Major sections, eg. functions, data areas. 288 | 289 | Equals () Major sub-sections 290 | 291 | Minus () Minor sub-sections 292 | 293 | e.g. 294 | 295 | 296 | 297 | 298 | 299 | 300 | 301 | 302 | 303 | 304 | 305 | 306 | 307 | 308 | 309 | 310 | 311 | -------------------------------------------------------------------------------- /test/expected/other/haskell.txt: -------------------------------------------------------------------------------- 1 | 2 | 3 | putStrLn "Wikipedia" 4 | -------------------------------------------------------------------------------- /test/expected/other/lua.txt: -------------------------------------------------------------------------------- 1 | Lua 2 | The Lua programming language uses double-hyphens, `--`, for single line comments in a similar way to Ada, Eiffel, Haskell, SQL and VHDL languages. Lua also has block comments, which start with `--[[` and run until a closing `]]` 3 | 4 | For example: 5 | 6 | 7 | print(20) 8 | A common technique to comment out a piece of code,[44] is to enclose the code between `--[[` and `--]]`, as below: 9 | 10 | 11 | 12 | In this case, it's possible to reactivate the code by adding a single hyphen to the first line: 13 | 14 | 15 | print(10) 16 | 17 | 18 | In the first example, the `--[[` in the first line starts a long comment, and the two hyphens in the last line are still inside that comment. In the second example, the sequence `---[[` starts an ordinary, single-line comment, so that the first and the last lines become independent comments. In this case, the print is outside comments. In this case, the last line becomes an independent comment, as it starts with `--`. 19 | 20 | Long comments in Lua can be more complex than these, as you can read in the section called "Long strings" c.f. Programming in Lua. 21 | -------------------------------------------------------------------------------- /test/expected/other/matlab.txt: -------------------------------------------------------------------------------- 1 | MATLAB 2 | In MATLAB's programming language, the '%' character indicates a single-line comment. Multi line comments are also available via `%{` and `%}` brackets and can be nested, e.g. 3 | 4 | 5 | d = [0 -1 0]; 6 | 7 | 8 | seq = d .* (x - c).^n ./(factorial(n)) 9 | 10 | 11 | approx = sum(seq) 12 | -------------------------------------------------------------------------------- /test/expected/other/ocaml.txt: -------------------------------------------------------------------------------- 1 | OCaml 2 | OCaml uses nestable comments, which is useful when commenting a code block. 3 | 4 | codeLine 5 | -------------------------------------------------------------------------------- /test/expected/other/pascal.txt: -------------------------------------------------------------------------------- 1 | 2 | columnDifference := testColumn - column; 3 | if (row + columnDifference = testRow) or 4 | ....... 5 | -------------------------------------------------------------------------------- /test/expected/other/perl.txt: -------------------------------------------------------------------------------- 1 | 2 | 3 | my $s = "Wikipedia"; 4 | print $s . "\n"; 5 | -------------------------------------------------------------------------------- /test/expected/other/php.txt: -------------------------------------------------------------------------------- 1 | PHP supports 'C', 'C++' and Unix shell-style (Perl style) comments. For example: 2 | 3 | 8 | The "one-line" comment styles only comment to the end of the line or the current block of PHP code, whichever comes first. This means that HTML code after `// ... ?>` or `# ... ?>` WILL be printed: ?> breaks out of PHP mode and returns to HTML mode, and `//` or `#` cannot influence that. If the asp_tags configuration directive is enabled, it behaves the same with `// %>` and `# %>`. However, the tag doesn't break out of PHP mode in a one-line comment. 9 | 10 |The header above will say 'This is an example'.
12 | 'C' style comments end at the first `*/` encountered. Make sure you don't nest 'C' style comments. It is easy to make this mistake if you are trying to comment out a large block of code. 13 | 14 | 16 | -------------------------------------------------------------------------------- /test/expected/other/python.txt: -------------------------------------------------------------------------------- 1 | Python 2 | Inline comments in Python use the hash ('#') character, as in the two examples in this code: 3 | 4 | 5 | print("Hello World!") 6 | Block comments, as defined in this article, don't technically exist in Python.[49] A bare string literal represented by a triple-quoted string can be used[50] but is not ignored by the interpreter in the same way that "#" comment is. In the examples below, the triple double-quoted strings act in this way as comments, but are also treated as docstrings: 7 | 8 | 9 | 10 | class MyClass(object): 11 | 12 | 13 | def my_method(self): 14 | 15 | 16 | def my_function(): 17 | 18 | -------------------------------------------------------------------------------- /test/expected/other/ruby.txt: -------------------------------------------------------------------------------- 1 | Ruby 2 | Comments in Ruby. 3 | 4 | Single line commenting: (line starts with hash "#") 5 | 6 | puts "This is not a comment" 7 | 8 | 9 | 10 | puts "This is not a comment" 11 | Multi-line commenting: (comments goes between keywords "begin" and "end") 12 | 13 | puts "This is not a comment" 14 | 15 | 16 | 17 | puts "This is not a comment" 18 | -------------------------------------------------------------------------------- /test/expected/other/shebang.txt: -------------------------------------------------------------------------------- 1 | 2 | Hello world! 3 | -------------------------------------------------------------------------------- /test/expected/other/sql.txt: -------------------------------------------------------------------------------- 1 | SQL 2 | Comments in SQL are in single-line-only form, when using two dashes: 3 | 4 | 5 | 6 | SELECT COUNT(*) 7 | FROM Authors 8 | WHERE Authors.name = 'Smith'; 9 | 10 | -------------------------------------------------------------------------------- /test/expected/other/swift.txt: -------------------------------------------------------------------------------- 1 | Swift 2 | Single-line comments begin with two forward-slashes (`//`): 3 | 4 | 5 | Multiline comments start with a forward-slash followed by an asterisk (`/*`) and end with an asterisk followed by a forward-slash (`*/`): 6 | 7 | Multiline comments in Swift can be nested inside other multiline comments. You write nested comments by starting a multiline comment block and then starting a second multiline comment within the first block. The second block is then closed, followed by the first block: 8 | 9 | -------------------------------------------------------------------------------- /test/expected/strip-all.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | var foo = function() {}; 4 | 5 | var bar = function() {}; 6 | 7 | var baz = '//bar baz not a comment'; 8 | 9 | 10 | var qux = function() { 11 | 12 | 13 | var some = true; 14 | 15 | var fafa = true; 16 | 17 | var but = 'not'; 18 | }; 19 | 20 | 21 | 22 | var fun = false; 23 | var path = '/path/to/*/something/that/not/be/stripped.js'; 24 | var globstar = '/path//to//globstar/not/be/stripped/**/*.js'; -------------------------------------------------------------------------------- /test/expected/strip-keep-block.js: -------------------------------------------------------------------------------- 1 | /*! 2 | * strip this multiline 3 | * block comment 4 | */ 5 | 'use strict'; 6 | 7 | /**! 8 | * and this multiline 9 | * block comment 10 | */ 11 | var foo = function() {}; 12 | 13 | var bar = function() {}; 14 | 15 | var baz = '//bar baz not a comment'; 16 | 17 | // this single-line line comment 18 | var qux = function() { 19 | // this multiline 20 | // line comment 21 | var some = true; 22 | //this 23 | var fafa = true; //and this 24 | // var also = 'that'; 25 | var but = 'not'; //! that comment 26 | }; 27 | 28 | // also this multiline 29 | // line comment 30 | var fun = false; 31 | var path = '/path/to/*/something/that/not/be/stripped.js'; 32 | var globstar = '/path//to//globstar/not/be/stripped/**/*.js'; -------------------------------------------------------------------------------- /test/expected/strip-keep-line.js: -------------------------------------------------------------------------------- 1 | /** 2 | * this block comment 3 | * will not be striped 4 | */ 5 | 6 | 'use strict'; 7 | 8 | //! and this multiline 9 | //! block comment 10 | var foo = function(/* and these single-line block comment */) {}; 11 | 12 | /** 13 | * and this 14 | * multiline block 15 | * comment 16 | */ 17 | var bar = function(/* and that */) {}; 18 | 19 | 20 | var baz = function() { 21 | 22 | 23 | var some = true; 24 | 25 | var fafa = true; 26 | 27 | var but = 'not'; //! that comment 28 | }; 29 | 30 | var path = '/path/to/*/something/that/not/be/stripped.js'; 31 | var globstar = '/path/to/globstar/not/be/stripped/**/*.js'; 32 | -------------------------------------------------------------------------------- /test/expected/strip-keep-newlines.js: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 'use strict'; 6 | 7 | 8 | 9 | 10 | 11 | var foo = function() {}; 12 | 13 | 14 | 15 | 16 | 17 | 18 | var bar = function() {}; 19 | 20 | var baz = '//bar baz not a comment'; 21 | 22 | 23 | var qux = function() { 24 | 25 | 26 | var some = true; 27 | 28 | var fafa = true; 29 | 30 | var but = 'not'; 31 | }; 32 | 33 | 34 | 35 | var fun = false; 36 | var path = '/path/to/*/something/that/not/be/stripped.js'; 37 | var globstar = '/path//to//globstar/not/be/stripped/**/*.js'; -------------------------------------------------------------------------------- /test/fixtures/banner.js: -------------------------------------------------------------------------------- 1 | /*! 2 | * update-bannertext
2 | 7 |More text
8 | 13 | -------------------------------------------------------------------------------- /test/fixtures/html/quoted.html: -------------------------------------------------------------------------------- 1 | 12.1.6 Comments 2 | Comments must have the following format: 3 | 4 | The string "", or "--!>", nor end with the string "". 7 | 8 | The text is allowed to end with the string " and . 9 | -------------------------------------------------------------------------------- /test/fixtures/line.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | // ------------------------- 3 | // This is the comment body. 4 | // ------------------------- 5 | const foo = 'bar'; // another line 6 | -------------------------------------------------------------------------------- /test/fixtures/no-comment.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | process.stdout.write('string literals: '); 4 | console.dir({ 5 | str0: ''', 6 | str1: """, 7 | str2: ". // ' \\ . // ' \\ .", 8 | }); 9 | 10 | process.stdout.write('RegExp literals: '); 11 | console.dir({ 12 | regexp0: /I'm the easiest in Chomsky hierarchy!/, 13 | }); 14 | -------------------------------------------------------------------------------- /test/fixtures/other/AppleScript.txt: -------------------------------------------------------------------------------- 1 | (* test diagonals *) 2 | columnDifference := testColumn - column; 3 | if (row + columnDifference = testRow) or 4 | ....... 5 | -------------------------------------------------------------------------------- /test/fixtures/other/ada.txt: -------------------------------------------------------------------------------- 1 | Ada 2 | The Ada programming language uses '--' to indicate a comment up to the end of the line. 3 | 4 | For example: 5 | 6 | -- the air traffic controller task takes requests for takeoff and landing 7 | task type Controller (My_Runway: Runway_Access) is 8 | -- task entries for synchronous message passing 9 | entry Request_Takeoff (ID: in Airplane_ID; Takeoff: out Runway_Access); 10 | entry Request_Approach(ID: in Airplane_ID; Approach: out Runway_Access); 11 | end Controller; 12 | -------------------------------------------------------------------------------- /test/fixtures/other/apl.txt: -------------------------------------------------------------------------------- 1 | ⍝ Now add the numbers: 2 | c←a+b ⍝ addition 3 | -------------------------------------------------------------------------------- /test/fixtures/other/c.txt: -------------------------------------------------------------------------------- 1 | CHAPTER 4 : Commenting 2 | PART 2 : COMMENTING AND NAMING 3 | 4 | CHAPTER 4 : Commenting 5 | 4.1 Commenting fundamentals 6 | 4.2 Comment types 7 | 4.3 Header comments 8 | 4.4 File Header comment 9 | 4.5 Function header comments 10 | 4.6 Block comments 11 | 4.7 Trailing comments 12 | 4.8 Commenting data 13 | 4.9 The preprocessor and comments 14 | 4.10 Summary 15 | 16 | <--Prev page | Next page --> 17 | 18 | 4.6 Block comments 19 | Block comments are typically found within functions, between 'chunks' of code. They also appear in other parts of code, for example at the start of chunks of data. There are a number of common approaches to block comments, several of which are discussed below. 20 | 21 | 4.6.1 Comment size 22 | There are about three different classifications of block comment, depending on its size: 23 | 24 | A single line comment will commonly describe a simple item. 25 | A multiple line comment, up to about 5 lines will summarize a more complex item or set of items. 26 | A longer comment will describe even more, although this is now tending towards a major header comment. 27 | Generally, it must be remembered that a block comment has a cost in vertical space and should give value for money. For example, it may be overkill for a block comment to be bigger than the chunk of function code that it describes. 28 | 29 | 4.6.2 Positioning the comment 30 | A block comment usually describes code below it. This association can be made clearer by using some method to explicitly associate it more closely with the code that it describes. 31 | 32 | Using blank lines 33 | A simple principle is to use a blank line above the comment to physically place it closer to the line below than the line above: 34 | 35 | 36 | 37 | ResetParms(); 38 | 39 | /* Close all remaining open windows */ 40 | for ( Win = 0; Win < NofWins; Win++ ) 41 | CloseWin( Win ); 42 | 43 | 44 | 45 | This, however, causes a possible problem where the comment and the code are not immediately distiguishable. A solution, at the cost of more vertical space, is to put a blank line below the comment: 46 | 47 | 48 | 49 | ResetParms(); 50 | 51 | /* Close all remaining open windows */ 52 | 53 | for ( Win = 0; Win < NofWins; Win++ ) 54 | CloseWin( Win ); 55 | 56 | 57 | 58 | Indenting the comment 59 | A common method of positioning is to vertically align the comment with the current indent level. This helps to associate the comment with the code below, and preserves the line of indentation. However, this reduces the amount of horizontal space available for comment, particularly at deeper levels of nesting, and may make it more difficult to distinguish between comments and code: 60 | 61 | 62 | 63 | ResetParms(); 64 | 65 | /* Close all remaining open windows */ 66 | for ( Win = 0; Win < NofWins; Win++ ) 67 | CloseWin( Win ); 68 | 69 | 70 | 71 | 4.6.3 Enclosing the comment 72 | When block comments cover multiple lines, it is only necessary to use the opening and closing comment tokens. This, however, can result in the limits of the comment becoming less than immediately obvious: 73 | 74 | 75 | 76 | /* Check for all corrupt nodes and add these to the 77 | Bad Data list. Any clear nodes found are added to the 78 | Free Data list. */ 79 | CheckNodes( DB_Nodes ); 80 | 81 | 82 | 83 | A simple principle that can be used in most cases to clarify the limits of multi-line comments, is to put the closing '*/' directly under the opening '*/' (in a similar manner to braces). 84 | 85 | 86 | 87 | /* Check for all corrupt nodes and add these to the 88 | Bad Data list. Any clear nodes found are added to the 89 | Free Data list. 90 | */ 91 | CheckNodes( DB_Nodes ); 92 | 93 | 94 | 95 | However, reading each line from the left, it is still not immediately clear which line is a comment and which line is not, particularly if the comment is long, and contains blank lines. 96 | 97 | Enclosing from the left 98 | In the previous example, you can clearly delimit the comment one line at a time by making the first character that is read an asterisk. This is using the principle of explicitness to say each time, "This is a comment. It is not code." 99 | 100 | 101 | 102 | /* Check for all corrupt nodes and add these to the 103 | * Bad Data list. Any clear nodes found are added to the 104 | * Free Data list. 105 | */ 106 | CheckNodes( DB_Nodes ); 107 | 108 | 109 | 110 | There are several common variant on this, such as putting the opening '/*' on a line by itself, thus ensuring an almost-blank line before the comment and enabling easier line insertion after it. Also, the asterisk may be always put in column two or two asterisks can be used on text lines, to emphasize the comment and to be tidy in having two comment characters per line. Some horizontal space can be saved by using spaces instead of tabs to separate the text from the asterisk: 111 | 112 | 113 | 114 | /* 115 | ** Check for all corrupt nodes and add these to the 116 | ** Bad Data list. Any clear nodes found are added to the 117 | ** Free Data list. 118 | */ 119 | CheckNodes( DB_Nodes ); 120 | /* 121 | * Alternative comment block format.. 122 | * ..which puts one asterisk always in column 2 123 | */ 124 | 125 | 126 | 127 | Enclosing from above 128 | An alternative or an addition to white space as a method of distinguishing comments from code is to put a bar above the comment, but not below it. This dissociates the comment from the code above, whilst emphasizing its association with the code below. 129 | 130 | 131 | 132 | /*********************************************************** 133 | * Check for all corrupt nodes and add these to the 134 | * Bad Data list. Any clear nodes found are added to the 135 | * Free Data list. 136 | */ 137 | CheckNodes( DB_Nodes ); 138 | 139 | 140 | 141 | Enclosing from below 142 | The comment can be dissociated more from the code below by putting a bar below it too. It is being tidy to keep it the same length as the top line. The dissociation can be further emphasized with a blank line between the comment and the code: 143 | 144 | 145 | 146 | /************************************************************ 147 | * Check for all corrupt nodes and add these to the 148 | * Bad Data list. Any clear nodes found are added to the 149 | * Free Data list. 150 | ************************************************************/ 151 | 152 | CheckNodes( DB_Nodes ); 153 | 154 | 155 | 156 | Note that the final '*/' is no longer below the opening '/*'. This is not so important as the limits of the comment block are very clear, although there is a danger of missing the final '/', resulting in the code below being commented out. 157 | 158 | A status comment, which describes the code above it, can be enclosed at the bottom, but not the top, to emphasize its association. 159 | 160 | 161 | 162 | /* 163 | * All open databases have now been closed, with all 164 | * signs of corruption reported to the corrupt data 165 | * log. It is now safe to shut the system down. 166 | ************************************************************/ 167 | 168 | 169 | 170 | Enclosing from the right 171 | The final step is now to tidily fill in the right hand side of the box, although this may be considered to be more trouble than it is worth, as it makes editing the comment text less easy. 172 | 173 | 174 | 175 | /************************************************************ 176 | * Check for all corrupt nodes and add these to the * 177 | * Bad Data list. Any clear nodes found are added to the * 178 | * Free Data list. * 179 | *************************************************************/ 180 | 181 | 182 | 183 | A simplification of the rules about where to place the '/*' and '*/' tokens is to insist that all comments should have matching tokens on the same line. Thus all comment lines are automatically enclosed from the right and the left. 184 | 185 | 186 | 187 | /************************************************************/ 188 | /* Check for all corrupt nodes and add these to the */ 189 | /* Bad Data list. Any clear nodes found are added to the */ 190 | /* Free Data list. */ 191 | /************************************************************/ 192 | 193 | 194 | 195 | With this rule, enclosure from the top and bottom may still be optional. The right hand margin may stay justified or may collapse to a ragged right margin, which eases editing but is not as tidy: 196 | 197 | 198 | 199 | /* Check for all corrupt nodes and add these to the */ 200 | /* Bad Data list. Any clear nodes found are added to the */ 201 | /* Free Data list. */ 202 | 203 | 204 | 205 | 4.6.4 Delimiters 206 | Comments need not be used for text comments: they may also be used to separate out distinct pieces of code. 207 | 208 | Separating chunks 209 | Drawing lines across the page not only separates the code from the comment, but also separates individual chunks of code, making the chunks easier to see and understand. As these are effectively single-line block comments, they can include simple comments: 210 | 211 | 212 | 213 | /*---- Close all open files ---------------------------------------*/ 214 | 215 | for ( FileNo = 0; FileNo < NofFilesOpen; FileNo++ ) 216 | { 217 | ErrNo = CloseFile( FileHandle[FileNo] ); 218 | if ( ErrNo != 0 ) 219 | { 220 | FileError( ErrNo ); 221 | } 222 | } 223 | 224 | /*---- Print shutdown message ------------------------------------*/ 225 | 226 | printf( "System closing down,\n" ); 227 | printf( "Remove all tapes and secure in safe.\n"); 228 | 229 | /*---- Lock terminal off ------------------------------------------*/ 230 | ... 231 | 232 | 233 | 234 | Multi-line block comments can also a similar scheme, whereby the text in the line is an effective summary for the comment block. 235 | 236 | 237 | 238 | /*---- Check window status ----------------------------------------- 239 | * All windows (including closed ones) must now be checked 240 | * to ensure all outstanding actions have been completed. 241 | *-------------------------------------------------------------------*/ 242 | 243 | ----------------------------------------------------------------------> 244 | 245 | Data/Code delimiters 246 | It can be difficult to immediately find the beginning of the code at the start of a function. For example, a reader might miss the first statement (which may be mistaken for a data declaration). 247 | 248 | 249 | 250 | int 251 | ReadDoorStatus( S_DOOR *Door ) 252 | 253 | { 254 | int DoorType; /* Door construction - WOOD, METAL, etc. */ 255 | int LockType; /* Make of lock - CHUBB, YALE, etc. */ 256 | DoorType = WOOD; /* set default for door construction */ 257 | 258 | LockType = Door->Lock; <------ reader may read code from here! 259 | 260 | 261 | 262 | However, if we put a line across at the start of the data and code sections, no mistakes may be made, and the start of the data and code sections can instantly be found. 263 | 264 | 265 | 266 | int 267 | ReadDoorStatus( S_DOOR *Door ) 268 | 269 | { 270 | /*---- Data --------------------------------------------------------*/ 271 | 272 | int DoorType; /* Door construction - WOOD, METAL, etc. */ 273 | int LockType; /* Make of lock - CHUBB, YALE, etc. */ 274 | 275 | /*---- Code --------------------------------------------------------*/ 276 | 277 | DoorType = WOOD; /* set default for door construction */ 278 | LockType = Door->Lock; 279 | 280 | 281 | 282 | Delimiter 'weight' 283 | The 'weight' of the delimiter can be used to indicate importance of the section of code or data that is being delimited. The symbols used may be for single line delimiters, or to bound multi-line comment blocks. 284 | 285 | A simple scheme would be: 286 | 287 | Asterisks (/********/) Major sections, eg. functions, data areas. 288 | 289 | Equals (/*======*/) Major sub-sections 290 | 291 | Minus (/*------*/) Minor sub-sections 292 | 293 | e.g. 294 | 295 | 296 | 297 | /******************************************************************** 298 | * FireOnEnemy( ShipType ) 299 | ... 300 | 301 | /*==== Prepare cannon for firing ===================================*/ 302 | 303 | /*---- Load cannon -------------------------------------------------*/ 304 | ... 305 | 306 | /*---- Open gun port doors -----------------------------------------*/ 307 | ... 308 | 309 | /*==== Fire and retract cannon =====================================*/ 310 | ... 311 | -------------------------------------------------------------------------------- /test/fixtures/other/haskell.txt: -------------------------------------------------------------------------------- 1 | {- this is a comment 2 | on more lines -} 3 | -- and this is a comment on one line 4 | putStrLn "Wikipedia" -- this is another comment 5 | -------------------------------------------------------------------------------- /test/fixtures/other/lua.txt: -------------------------------------------------------------------------------- 1 | Lua 2 | The Lua programming language uses double-hyphens, `--`, for single line comments in a similar way to Ada, Eiffel, Haskell, SQL and VHDL languages. Lua also has block comments, which start with `--[[` and run until a closing `]]` 3 | 4 | For example: 5 | 6 | --[[A multi-line 7 | long comment 8 | ]] 9 | print(20) -- print the result 10 | A common technique to comment out a piece of code,[44] is to enclose the code between `--[[` and `--]]`, as below: 11 | 12 | --[[ 13 | print(10) 14 | --]] 15 | -- no action (commented out) 16 | In this case, it's possible to reactivate the code by adding a single hyphen to the first line: 17 | 18 | ---[[ 19 | print(10) 20 | --]] 21 | --> 10 22 | In the first example, the `--[[` in the first line starts a long comment, and the two hyphens in the last line are still inside that comment. In the second example, the sequence `---[[` starts an ordinary, single-line comment, so that the first and the last lines become independent comments. In this case, the print is outside comments. In this case, the last line becomes an independent comment, as it starts with `--`. 23 | 24 | Long comments in Lua can be more complex than these, as you can read in the section called "Long strings" c.f. Programming in Lua. 25 | -------------------------------------------------------------------------------- /test/fixtures/other/matlab.txt: -------------------------------------------------------------------------------- 1 | MATLAB 2 | In MATLAB's programming language, the '%' character indicates a single-line comment. Multi line comments are also available via `%{` and `%}` brackets and can be nested, e.g. 3 | 4 | % These are the derivatives for each term 5 | d = [0 -1 0]; 6 | 7 | %{ 8 | %{ 9 | (Example of a nested comment, indentation is for cosmetics (and ignored).) 10 | %} 11 | We form the sequence, following the Taylor formula. 12 | Note that we're operating on a vector. 13 | %} 14 | seq = d .* (x - c).^n ./(factorial(n)) 15 | 16 | % We add-up to get the Taylor approximation 17 | approx = sum(seq) 18 | -------------------------------------------------------------------------------- /test/fixtures/other/ocaml.txt: -------------------------------------------------------------------------------- 1 | OCaml 2 | OCaml uses nestable comments, which is useful when commenting a code block. 3 | 4 | codeLine(* comment level 1(*comment level 2*)*) 5 | -------------------------------------------------------------------------------- /test/fixtures/other/pascal.txt: -------------------------------------------------------------------------------- 1 | (* test diagonals *) 2 | columnDifference := testColumn - column; 3 | if (row + columnDifference = testRow) or 4 | ....... 5 | -------------------------------------------------------------------------------- /test/fixtures/other/perl.txt: -------------------------------------------------------------------------------- 1 | # A simple example 2 | # 3 | my $s = "Wikipedia"; # Sets the variable s to "Wikipedia". 4 | print $s . "\n"; # Add a newline character after printing 5 | -------------------------------------------------------------------------------- /test/fixtures/other/php.txt: -------------------------------------------------------------------------------- 1 | PHP supports 'C', 'C++' and Unix shell-style (Perl style) comments. For example: 2 | 3 | 10 | The "one-line" comment styles only comment to the end of the line or the current block of PHP code, whichever comes first. This means that HTML code after `// ... ?>` or `# ... ?>` WILL be printed: ?> breaks out of PHP mode and returns to HTML mode, and `//` or `#` cannot influence that. If the asp_tags configuration directive is enabled, it behaves the same with `// %>` and `# %>`. However, the tag doesn't break out of PHP mode in a one-line comment. 11 | 12 |The header above will say 'This is an example'.
14 | 'C' style comments end at the first `*/` encountered. Make sure you don't nest 'C' style comments. It is easy to make this mistake if you are trying to comment out a large block of code. 15 | 16 | 21 | -------------------------------------------------------------------------------- /test/fixtures/other/python.txt: -------------------------------------------------------------------------------- 1 | Python 2 | Inline comments in Python use the hash ('#') character, as in the two examples in this code: 3 | 4 | # This program prints "Hello World" to the screen 5 | print("Hello World!") # Note the new syntax 6 | Block comments, as defined in this article, don't technically exist in Python.[49] A bare string literal represented by a triple-quoted string can be used[50] but is not ignored by the interpreter in the same way that "#" comment is. In the examples below, the triple double-quoted strings act in this way as comments, but are also treated as docstrings: 7 | 8 | """ 9 | Assuming this is file mymodule.py, then this string, being the 10 | first statement in the file, will become the "mymodule" module's 11 | docstring when the file is imported. 12 | """ 13 | 14 | class MyClass(object): 15 | """The class's docstring""" 16 | 17 | def my_method(self): 18 | """The method's docstring""" 19 | 20 | def my_function(): 21 | """The function's docstring""" 22 | -------------------------------------------------------------------------------- /test/fixtures/other/ruby.txt: -------------------------------------------------------------------------------- 1 | Ruby 2 | Comments in Ruby. 3 | 4 | Single line commenting: (line starts with hash "#") 5 | 6 | puts "This is not a comment" 7 | 8 | # this is a comment 9 | 10 | puts "This is not a comment" 11 | Multi-line commenting: (comments goes between keywords "begin" and "end") 12 | 13 | puts "This is not a comment" 14 | 15 | =begin 16 | 17 | whatever goes in these lines 18 | 19 | is just for the human reader 20 | 21 | =end 22 | 23 | puts "This is not a comment" 24 | -------------------------------------------------------------------------------- /test/fixtures/other/shebang.txt: -------------------------------------------------------------------------------- 1 | #!/bin/cat 2 | Hello world! 3 | -------------------------------------------------------------------------------- /test/fixtures/other/sql.txt: -------------------------------------------------------------------------------- 1 | SQL 2 | Comments in SQL are in single-line-only form, when using two dashes: 3 | 4 | -- This is a single line comment 5 | -- followed by a second line 6 | SELECT COUNT(*) 7 | FROM Authors 8 | WHERE Authors.name = 'Smith'; -- Note: we only want 'smith' 9 | -- this comment appears after SQL code 10 | -------------------------------------------------------------------------------- /test/fixtures/other/swift.txt: -------------------------------------------------------------------------------- 1 | Swift 2 | Single-line comments begin with two forward-slashes (`//`): 3 | 4 | // This is a comment. 5 | Multiline comments start with a forward-slash followed by an asterisk (`/*`) and end with an asterisk followed by a forward-slash (`*/`): 6 | 7 | /* This is also a comment 8 | but is written over multiple lines. */ 9 | Multiline comments in Swift can be nested inside other multiline comments. You write nested comments by starting a multiline comment block and then starting a second multiline comment within the first block. The second block is then closed, followed by the first block: 10 | 11 | /* This is the start of the first multiline comment. 12 | /* This is the second, nested multiline comment. */ 13 | This is the end of the first multiline comment. */ 14 | -------------------------------------------------------------------------------- /test/fixtures/quoted-strings.js: -------------------------------------------------------------------------------- 1 | window.amino_cec_callback = function (tag, source, destination, body) { 2 | debug("///////////// cec_callback ////////////////////"); 3 | debug(tag + " " + source + " " + destination + " " + body); 4 | debug("///////////// cec_callback ////////////////////"); 5 | }; 6 | 7 | const foo = { 8 | "config": { 9 | "properties": { 10 | "device_id": { 11 | "type": "string", 12 | "title": "Device ID", 13 | "label": { 14 | "$ref": "/rpcs/device_ids#thermostats/*/{name}" 15 | }, 16 | "oneOf": [{ 17 | "$ref": "/rpcs/device_ids#thermostats/*/{device_id}" 18 | }] 19 | } 20 | }, 21 | "required": ["device_id"], 22 | "disposition": ["device_id"] 23 | } 24 | }; -------------------------------------------------------------------------------- /test/fixtures/strip-all.js: -------------------------------------------------------------------------------- 1 | /*! 2 | * strip this multiline 3 | * block comment 4 | */ 5 | 'use strict'; 6 | 7 | /**! 8 | * and this multiline 9 | * block comment 10 | */ 11 | var foo = function(/* and these single-line block comment */) {}; 12 | 13 | /** 14 | * and this 15 | * multiline block 16 | * comment 17 | */ 18 | var bar = function(/* and that */) {}; 19 | 20 | var baz = '//bar baz not a comment'; 21 | 22 | // this single-line line comment 23 | var qux = function() { 24 | // this multiline 25 | // line comment 26 | var some = true; 27 | //this 28 | var fafa = true; //and this 29 | // var also = 'that'; 30 | var but = 'not'; //! that comment 31 | }; 32 | 33 | // also this multiline 34 | // line comment 35 | var fun = false; 36 | var path = '/path/to/*/something/that/not/be/stripped.js'; 37 | var globstar = '/path//to//globstar/not/be/stripped/**/*.js'; -------------------------------------------------------------------------------- /test/fixtures/strip-keep-line.js: -------------------------------------------------------------------------------- 1 | /** 2 | * this block comment 3 | * will not be striped 4 | */ 5 | 6 | 'use strict'; 7 | 8 | //! and this multiline 9 | //! block comment 10 | var foo = function(/* and these single-line block comment */) {}; 11 | 12 | /** 13 | * and this 14 | * multiline block 15 | * comment 16 | */ 17 | var bar = function(/* and that */) {}; 18 | 19 | //will be removed 20 | var baz = function() { 21 | // this multiline 22 | // line comment 23 | var some = true; 24 | // will be 25 | var fafa = true; 26 | // var removed = 'yes'; 27 | var but = 'not'; //! that comment 28 | }; 29 | 30 | var path = '/path/to/*/something/that/not/be/stripped.js'; 31 | var globstar = '/path/to/globstar/not/be/stripped/**/*.js'; 32 | -------------------------------------------------------------------------------- /test/other.js: -------------------------------------------------------------------------------- 1 | /*! 2 | * strip-comments