Thursday 4 October 2018
Scala 2.12.7 adds support for markdown tables in Scaladoc comments.
A Simple Example
The markdown for tables follows GitHub Flavored Markdown with some restrictions.
This table shows all three available table elements,
| Trait | Implementations | | --- | --- | | Set | HashSet, HashTrieSet | | Seq | List, Vector, Empty | | Map | HashTrieMap, ListMap |
A table is comprised of,
- A header row
- A delimiter row
- Zero or more data rows
This is how the above markdown renders,
On an incidental note, there is no requirement to align header and cell markdown pipes. This is done in the examples to make them easier to scan.
GitHub Flavored Markdown Conformance
Scaladoc tables support the GitHub Flavored Markdown Spec Table Extension.
There are some restrictions,
- Every row must start and end with the pipe
- Rows markdown must start on the left edge of the Scala comment
- The final row must be followed by a blank line
These restrictions do not restrict the types of tables that can be created but do have the benefit of allowing simple Scaladoc parsing code.
Picking a popular markdown flavor brings several advantages over creating yet another table markdown variation including,
- No need to explain a new approach
- IDEs and documentation tools can take advantage of existing markdown parsing libraries
Header Cells, Data Cells
Cell content supports the standard inline styling syntax including bold, italic, monospace, underline, superscript, subscript and links.
This two table example includes bold, monospace, italic, superscript and a link,
/** * | Title | ISBN | Authors | * | :---: | --- | --- | * | '''Structured Programming''' | `0-12-200550-3` | ''Dahl, Dijkstra and Hoare'' | * | '''Purely functional data structures'''^1^ | `0-521-66350-4` | ''Okasaki'' | * * | Note | Comment | * | ---: | --- | * | 1 | [[https://cambridge.org Cambridge University Press]], 1998| */ trait Bibliography
Markdown paid, we get this reward,
Breaking content over several lines is not supported in GFM tables. Use a
<br/> tag or go with HTML tables if you have needs beyond the simple tables supported by GFM.
Specify column alignments using hyphen and colon patterns.
|Delimiter Cell Content||Alignment Type|
Including pipe (
|) in content.
Scala 2.12.8 will support the escaping of the cell delimiter in cell content with
For a smorgasbord of examples take a look at examples.
Dotty and Scala 3
dotty now boosting its share of the development horizon it’s important to place GFM into a dottydoc and hence Scaladoc 3 context.
dottydoc supports the current Scaladoc 2.12 MediaWiki flavored markdown, but it also supports more contemporary flavors of markdown.
Within the realm of table markdown
dottydoc supports some extensions via the flexmark-java table extension.
flexmark-java allows tables to be defined using a more expressive variant of GFM table markdown. Tables you create now will have a route to being reused for
dottydoc API documentation.
Scala 2.11 Compatibility
Table markdown will not be interpreted by Scala 2.11 nor will it interfere with parsing.
Content using pipes will display in the generated Scaladoc with the pipes included as literal characters. Bear this in mind if cross compiling.
How can I help?
- Use Scaladoc tables
- Share your feedback on Discourse/Documentation