It is possible to include pieces of code in your documentation with the org.specs2.specification.Snippets
trait using the snippet
method to capture a block code with marker comments to delimit the parts you want to show.
What does this look like?
Here is an example of using the snippet
method:
s2"""
This is a multi-line string with a code snippet: ${ snippet {
def factorial(n: Int): Int = if (n == 1) n else (n * factorial(n - 1))
factorial(3) == 6
}}
"""
When you use the snippet
method, the reports will show:
This is a multi-line string with a code snippet:
def factorial(n: Int): Int = if (n == 1) n else (n * factorial(n - 1))
factorial(3) == 6
Since snippets are compiled code, you might have to include many declarations, like imports or variables definitions to make the code compile. This can make your documentation more verbose than necessary so you can hide those definitions by delimiting the code to show with some comments of the form // 8<--
:
s2"""
This is a snippet of code with one relevant line: ${ snippet {
// 8<--
def factorial(n: Int): Int = if (n == 1) n else (n * factorial(n - 1))
// 8<--
factorial(3) == 6
// 8<--
}}
"""
The snippet above will only show factorial(3) == 6
. You can repeat this pattern several times:
s2"""
This is a snippet of code with 2 relevant lines: ${ snippet {
// 8<--
def factorial(n: Int): Int = if (n == 1) n else (n * factorial(n - 1))
// 8<--
factorial(3) == 6
// 8<--
val n = 4
// 8<--
factorial(n) == 24
}}
"""
This just displays:
factorial(3) == 6
factorial(n) == 24
By default the last value of a Snippet is not shown but you can display it with the eval
method:
s2"""
This is a snippet of code with a result: ${ snippet {
factorial(3)
}.eval}
"""
This displays:
factorial(3)
> 6
It is possible to adjust the margin of captured source code by adding or removing whitespace:
s2"""
This is a snippet of code with a negative offset to align the code to the border of the screen: ${ snippet {
def factorial(n: Int): Int = if (n == 1) n else (n * factorial(n - 1))
factorial(3)
}.offsetIs(-3)}
"""
This displays:
factorial(3)
All of the settings above: cuts, offset,… are coming from an implicit SnippetParams
object that is changing the behavior of the created Snippets. You can choose, for a given scope, to replace these parameters with other ones and simply shadow the default parameters with your own, for example to always evaluate the snippets results:
implicit def snippetParams[T]: SnippetParams[T] = SnippetParams(evalCode = true)
The parameters you can set are:
name | description |
---|---|
trimExpression |
function that is trimming the expression from newlines or accolades |
cutter |
function to remove parts which must not be shown |
asCode |
function to render the resulting text (as Markdown for example) |
prompt |
function to display the evaluated result with a prompt |
evalCode |
boolean indicating if a snippet must be evaluated |
verify |
function checking the snippet value |