Where to find tutorials for scaladoc 2?

Question

I binged or googled for scaladoc 2.0 tutorial or example, I could not find anything, in fact not even a link to official scaladoc 2.0 documentation. Anyone know where to find one?

Bromley

Answer 1

docs.scala-lang.org is a more recent source of "Community-driven documentation for Scala" (thanks to the initiative lead by Heather Miller).
(as edited by Martin Konicek in David James's original answer) The Scaladoc page is quite up-to-date.

Martin Konicek asks in the comment how to make a simple Javadoc-like {@link}.
(And {@link} isn't mentioned in scala.tools.nsc.ast.DocComments.scala)

He mentions that Scaladoc uses [[fullyQualifiedName]] instead of {@link}.

---

Initial answer (July/Sept 2011)

Right now, the most complete source of information I know about Scaladoc2 is in the new scala-lang.org Wiki.

David James mentions in the comments the Syntax page, and the Tags and Annotations.

The author page has examples, including a what's new section:

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.

Tabulator

After digging around, I've found more content in the wiki you mentioned: Syntax and Tags and Annotations. – Childress

@MartinKonicek Note that github.com/scala/scala/blob/master/src/compiler/scala/tools/nsc/… doesn't mention @link. – Tabulator

@Tabulator Yes, now I know Scaladoc uses [[fullyQualifiedName]] instead of {@link}. – Neoplasty

@Martin excellent. Do you have an example of ScalaDoc with that tag used in it? I have edited the answer to include up-to-date links and your question about {@link} – Tabulator

Answer 2

I wrote a Scaladoc HOWTO over on github here.

It's a how-to written with Scaladoc itself so it serves as an example. I placed extra emphasis on how to get the package documentation to show up in your API, as this is not very clear in the official documentation.

Subvene

I noticed that you frequently used /*#! scaladoc */ in your source. Is this important? – Childress

No the !# notation is not required by Scaladoc. You may ignore it. It is meant to flag the type of coded comment that the file contains. – Subvene

Answer 3

The Scala Style Guide has a nice introductory page on scaladoc. I'd recommend it over the scala-lang.org wiki mentioned in @VonC's answer.

Childress

I'd recommend this resource over all the others as well. – Neoplasty

Answer 4

A condensed full example:

/** Creates [[mypackage.Person]] instances, taking a `String` argument. */
object Person {
  /** Create a [[mypackage.Person]] with a given name.
  *
  * This is another paragraph (note the empty line above) containing '''bold''',
  * ''italic'', `monospace`, __underline__, ^superscript^, and ,,subscript,,.
  * 
  * Example:
  * {{{
  * val person = Person("Bill")
  * }}}
  *
  * @param name their name
  * @return a new Person instance
  */
  def apply(name: String) = {}
}

Note that Scaladoc 2.9 does not support [[links]] to methods (like Javadoc's {@link type#instanceMethod(int, String)} or {@link type.staticMethod()}).

Neoplasty

Answer 5

This is the best Scaladoc guide I have found: https://gist.github.com/VladUreche/8396624. It is markdown text, so download it and use a markdown viewer plugin for your browser or paste it into http://markdownlivepreview.com/ to read it.

Subclavian