Named comment
Named comment is a comment that have a special format for programmatically referencing its content.
Table of contents:
Format and usage
The format of the named comment is:
/**Identifier**...
Any string...
*/
From the top, they are the start line, content line, and end line. Each should be on a separate line.
Let's see the following comment.
/**Sample**/
It looks like a single-line named comment or a multi-line comment, but it's a named comment.
An exception will occur because does not meet the format. This is because the start and end lines are not independent.
Let's modify this comment to the correct named comment.
/**Sample**
*/
We have now defined a comment named "Sample". Let's refer to this programmatically.
| 1: | /**Sample** |
| 2: | */ |
| 3: | |
| 4: | rice rr; |
| 5: | string namedComment = rr.Sample; |
We can now refer the "Sample". An empty string will be assigned to the namedComment. This is because "Sample" has no content line.
Start line
If the beginning of a multi-line comment matches the rules below, it is a named comment.
/**Identifier**
The identifier is sandwiched between /** and **. The identifier follows the rules for identifiers in the Rice language.
The start line specifies the name and command. If you specify a command, it will look like this:
/**Identifier**Command
Specifying the command is optional. The command will be described later.
The second term which splitted the entire start line by "**" is used as the name.
If there are three or more split results, the third term is the command. When specifying the command, specify "concat" or "trimcat". If any other command is specified, it will be ignored.
If the fourth and subsequent terms are present, those terms are ignored. You can use this to add comments to named comments.
/**Sample**concat**Comment for named comment.
*/
The start line must be an independent line. The content present on this line is never referenced as a named comment.
Content line
The content line is content what is referenced as a named comment. It is optional and there is no limit to the number of lines.
There are no restrictions on the content of the content line. You can also use characters that cannot be used in regular string literals. In particular, you can use double quotes as is.
If there are content lines, they are concatenated in the order of appearance to form a single character string. This concatenated string is the reference result.
You can control the concatenation method with the command on the start line.
End line
The end line is the line that contains the end symbol for multi-line comments.
The end line must be an independent line. The content present on this line is never referenced as a named comment.
Command
You can control how content lines are concatenated with the command. There are three modes for concatenating. They are "No control", "concat", "trimcat".
Specifying the command is optional. When specifying the command, specify "concat" or "trimcat". If any other command is specified, it will be ignored.
/**Sample**Comment for named comment.
*/
Command is "Comment for named comment.". In such a case, the command specification is ignored and mode is "No control".
No control
It inserts a newline character at the end of each line when concatenating content lines.
/**Sample**
function samplefunc() {
alert("Hello world!");
}
*/
The result of the reference is:
function samplefunc() {⏎
alert("Hello world!");⏎
}⏎
concat
It does not insert a newline character when concatenating content lines.
/**Sample**concat
function samplefunc() {
alert("Hello world!");
}
*/
The result of the reference is:
function samplefunc() { alert("Hello world!"); }
trimcat
When concatenating content lines, blanks at the beginning and end of the line are removed and no newline characters are inserted.
/**Sample**trimcat
function samplefunc() {
alert("Hello world!");
}
*/
The result of the reference is:
function samplefunc() {alert("Hello world!");}
If you want a reference result without newline caracters like a string literal, specify a command. "No control" mode is added a newline character at the end even if the reference result is a single line.
How to reference
References to named comments are made via variables in the rice class.
| 1: | /**Sample** |
| 2: | */ |
| 3: | |
| 4: | rice rr; |
| 5: | string namedComment = rr.Sample; |
| 6: | namedComment = rr.GetComment("Sample"); |