The effective code starts from the newline placed after the semicolon (:) and ends before the closing right curly bracket (}). The code indentation is treated as in code blocks, so the compiler removes the incidental white spaces and we can indent the code with respect to the closing right curly bracket (}). Check out the following figure:
Figure 2.14 – Indentation of code snippets
In the top example, the closing right curly bracket is aligned under the opening left curly bracket, while in the bottom example, we shifted the closing right curly bracket to the right.
Adding attributes
We can specify attributes for a @snippet via name = value pairs. For instance, we can provide a tip about the programming language of our snippet via the lang attribute. The value of the attribute is available to external tools and is present in the generated HTML. Here are two examples:
* {@snippet lang=”java” :
* Telemeter.Calibrate.at(0.00001);
* Telemeter telemeter = new Telemeter(0.15, 2, “IP54”);
* }
In the generated HTML, you’ll easily identify this attribute as:
<code class=”language-java”> … </code>
If the code is a structured text such as a properties file then you can follow this example:
* {@snippet lang=”properties” :
* telemeter.precision.default=42
* telemeter.clazz.default=2
* }
In the generated HTML, you’ll have:
<code class=”language-properties”></code>
Next, let’s see how can we alter what is displayed in a snippet.
Using markup comments and regions
We can visually alter a snippet of code via markup comments. A markup comment occurs at the end of the line and it contains one or more markup tags of form @name args, where args are commonly name=value pairs. Common markup comments include highlighting, linking, and content (text) modifications.
Highlighting
Highlighting a whole line can be done via @highlight without arguments as in the following figure:
Figure 2.15 – Highlighting a whole line of code
As you can see in this figure, the first line of code was bolded.If we want to highlight multiple lines then we can define regions. A region can be treated as anonymous or have an explicit name. An anonymous region is demarcated by the word region placed as an argument of the markup tag and the @end tag placed at the end of the region. Here is an example for highlighting two regions (an anonymous one and a named one (R1)):
Figure 2.16 – Highlighting a block a code using regions
Regular expressions allow us to highlight a certain part of the code. For instance, highlighting everything that occurs between quotes can be done via @highlight regex='”.*”‘. Or, highlighting only the word Calibrate can be done via the substring=”Calibrate” argument as in the following figure:
Figure 2.17 – Highlighting only the word “Calibrate”
Next, let’s talk about adding links in code.