Please note that the Scala wikis are in a state of flux. We strongly encourage you to add content but avoid creating permanent links. URLs will frequently change. For our long-term plans see this post by the doc czar.
Skip to end of metadata
Go to start of metadata

Commenting Symbols

Scaladoc comments have the same form than Javadoc comments. They start with: /** and end with */. Whilst Scala's syntax allows Scaladoc comments anywhere whitespace is allowed, comments are meaningful only in some selected places:

  • before a class, trait, or object declaration;
  • before a package object declaration (note that comments are not meaningful before packagings, see reference $9.2);
  • before a value member declaration (method, value, variable);
  • before a type member declaration (alias and abstract types).

The comment always relates to the declaration before which it is placed. A package object declaration can be used solely as a hook for a package comment, if required. Note that in the context above, “before a declaration” means before any annotations or modifiers that are linked to the declaration, if they exist.

Some wiki styles depend on the location of the left margin (list items, code blocks). The left margin for a line of text is either one of:

  • if the line starts with any number of spacing character, followed by a *, followed by another space character: the character following this space;
  • if the line starts with any number of spacing character, followed by a *, followed by a non-space character: the character following the *;
  • if the line does not start as above: the first character of the line.

The recommended style is to write Scaladoc comments as follows:

/** Start the comment here
  * and use the left star followed by a white space on every line.
  *
  * Even on empty paragraph-break lines.
  *
  * Note that the * on each line is aligned with the second * in /** so that the
  * left margin is on the same column on the first line and on subsequent ones.
  *
  * The closing scaladoc tag goes on its own, separate line.
  */
def document: Nothing

Comment Inheritance

A member that overrides or implements a commented member will automatically inherit the comment if it does not have one itself.

Parameter comments are inherited separately, so that the overall comment can be changed in the overriding member whilst still inheriting parameter comments, or vice-versa. If a member has multiple parameters and only some are redefined in the overriding member, other parameter comments will be inherited. Inheritance of parameter comments is based on parameter names; if parameter names are changed by overriding, comments will not be inherited.

Wiki-like Syntax in Documentation Source

Authors of documentation no longer have to use HTML tags in their comments. Instead, Scaladoc supports a wiki-like syntax very similar to that used in Trac. In general, Scaladoc authors should no longer use HTML tags in documentation as Scaladoc may in the future also generate documentation in other formats than HTML.

Wiki syntax is dependent of left-side alignment: the star marking the beginning of a Scaladoc line marks the beginning of the left side for parsing purposes (start-of-line markers are mandatory). Here is a small example of Scaladoc-supported wiki syntax.

/** This is a paragraph
  *
  * This is another paragraph (note the empty line above) containing '''bold''',
  * ''italic'', `monospace`,
  * __underline__, ^superscript^, and ,,subscript,, words.
  *
  * {{{
  * Multi-line code can be inserted as a block and will be printed as monospace
  * text.
  * It isn't parsed as Scala, with keyword highlighting, but may be in the
  * future.
  * }}}
  *
  * In the near future, wiki syntax will also support bullet or number lists as
  * well as links to the www and to other pages inside the documentation.
  */

Scaladoc comments should use wiki syntax if they require styling. The supported syntax is as follows.

Inline elements

  • Italic: ''text'' becomes text.
  • Bold: '''text''' becomes text.
  • Underline: __text__ becomes text.
  • Monospace: `text` becomes text.
  • Superscript: ^text^ becomes text.
  • Subscript: ,,text,, becomes text.
  • Entity links: [[scala.collection.Seq]] becomes a link to the corresponding entity like Seq. The entity must be linked using fully-qualified names (scala.collection.Seq instead of Seq); this requirement may be relaxed in a future release.
  • External links: [[http://scala-lang.org Scala web site]] becomes Scala web site. The URL part must start with a scheme name (like http:) and must not contain white space. The name part (Scala web site) is optional.

Block elements

  • Paragraphs: a blank line starts a new paragraph. Note that a "blank line" may contain a left margin * delimiter, as described above.
  • Code blocks: enclose between {{{ and }}}. See rule above for determining left margin.
  • Headings: =heading= defines a heading. Lower-level heading are obtained by using more = signs, like ===sub-heading===. A heading must be define on its own line.
  • List block: A list block is a sequence of list items of the same style and level, uninterrupted by other block elements.
    • Unordered list item: $ - item becomes a list item ($ signifies the left margin of a line (it doesn't appear in the code), note the space between the left margin and the dash). More leading space characters are allowed between the left margin and the dash: list items with the same number of leading spaces are at the same level, more space creates sub-levels.
    • Ordered list item: uses similar rules to the unordered item, but replace dash by one of 1., I., i., A. or a. for various numbering styles.

HTML element tags

HTML element tags are not recommended in Scaladoc, but are supported to maintain compatibility with existing documentation or when the wiki syntax is insufficient. If you are using HTML element tags in your documentation, you must be aware of the following.

The following block-level HTML elements are sanitised by Scaladoc, which internally converts them into equivalent wiki syntax: div, ol, ul, li, p and all headings. A sanitised element will loose its attributes. Other block-level elements (pre, table, etc.) are not sanitised. However, a comment that starts with a non-sanitised block-level element may not be rendered correctly; make sure to have a least one paragraph, heading, or similar block before it.

For an HTML element in a comment to be preserved as such in the documentation page, it must be recognised as valid. The following elements are recognised (in addition to the sanitised elements above):
a, abbr, acronym, address, area, b, bdo, big, blockquote, br, button, caption, code, cite, col, colgroup, dd, del, dfn, em, fieldset, form, hr, img, input, i, ins, kbd, label, legend, link, map, object, optgroup, option, param, pre, q, samp, select, small, span, strong, sub, sup, table, tbody, td, textarea, tfoot, th, thead, tr, tt, var. Furthermore, any string that has the structure of an HTML entity (as accepted by regular expression &\w+;) will also be recognised.

Any other HTML/XML element will be encoded so as to be visibly printed in the documentation.

In a wiki-syntax code block (using {{{), all HTML/XML elements will be encoded so as to be visibly printed in the documentation, including the recognised elements above. They will not function as markup elements. However, if a code block is defined using the pre element, recognised elements inside the block will be preserved.

Keep in mind that you rely on the documentation being generated in HTML, with a specific stylesheet. Scaladoc has an extensible documentation generator so that other formats may be generated. For this reason, recognised but non-sanitised HTML elements are not guaranteed to be kept by all generators. If you want to use HTML elements in your comment, we recommend you do not rely on them to obtain readable documentation, but instead use them for non-critial improvements.

Compile-time Error Checking

The Scaladoc comment parser will report invalid wiki syntax, such as unclosed formatting ('''bold for example), unclosed code blocks, or missing start-of-line markers

  • No labels

6 Comments

  1. The Wiki syntax example is inconsistent with the Wiki syntax definition. For example, monospace in the example uses backticks, while the section on Inline Elements shows double braces.

    (Page has been updated.)

  2. How are internal links to functions formatted (I guess this question also applies to the @see tag as well).  For example, say I have a class defined like this:

    class A {
    def doSomething (): Unit = {
    // ...
    }
    def doSomething (x: Int): Unit = {
    // ...
    }
    def doSomething (x: Int, y: Int): Unit = {
    // ...
    }
    // ...
    }

    Now, say I want to refer to a specific version of one of the doSomething functions in a Scaladoc comment.  In a Javadoc comment, I would write something like this:

    /**
    Javadoc: Refer to {@link A#doSomething(int,int)} for further info...
    */

    But that doesn't seem to match Scala's argument type syntax.  There's no documentation here (forgive me if I'm missing something) that describes how you would do this in Scaladoc.  Would this be the correct Scaladoc equivalent?

    /**
    Scaladoc: Refer to [[A.doSomething(Int,Int)]] for further info...
    */

    Thanks for your assistance!

  3. It would be helpful to have ScalaDoc copy images from source trees in a manner similar to how Javadocs works.

  4. @Mike Allen: Unfortunately the current version of scaladoc (2.9) does not support links to methods. There's a chance the 2.10 scaladoc might support them, but in a primitive form:

    [[com.mycompany.myproduct.SomeClass#doSomething]]

    that will take you to the first member with that name.

     

    @Mike Slinn: That's a good suggestion, can you please file a bug with a test case on http://issues.scala-lang.org?

  5. I just tried `monospace` and nothing happened, but <code>monospace</code> does work.

  6. Thanks for reminding me! I filed a bug for this, as I also noticed the problem: SI-8314 - Monospace with backquotes doesn't work in Scaladoc Open