How to format source code blocks in Scaladoc comments

As a quick note, if you want to embed a Scala source code example in your Scaladoc comments, just put the source code block in between {{{ and }}} characters in your comments, as shown in this example:

/**
  * Usage:
  *
  * {{{
  * val res = readTextFileAsTry("/etc/passed")
  * res match {
  *      case Success(lines) => lines.foreach(println)
  *      case Failure(s) => println(s"Failed, message is: $s")
  * }
  * }}}
  */
def readTextFileAsTry(filename: String): Try[List[String]] = {
    Try {
        val lines = using(io.Source.fromFile(filename)) { source =>
            (for (line <- source.getLines) yield line).toList
        }
        lines
    }
}

That “usage” example code block produces the Scaladoc shown in the image, as least as of Scala 2.12.

The Scaladoc for Library Authors page states, “Code blocks are contained within {{{ this }}} and may be multi-line. Indentation is relative to the starting * for the comment.” See that link and my Scaladoc documentation page for more information.