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?

score 18 · Accepted Answer · edited May 23 '17 at 12:16

18

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.

edited May 23 '17 at 12:16

Community

1
1

answered Jul 10 '11 at 09:38

VonC

1,262,500
529
4,410
5,250

After digging around, I've found more content in the wiki you mentioned: [Syntax](https://wiki.scala-lang.org/display/SW/Syntax) and [Tags and Annotations](https://wiki.scala-lang.org/display/SW/Tags+and+Annotations). – David J. Sep 25 '11 at 17:29
@MartinKonicek Note that https://github.com/scala/scala/blob/master/src/compiler/scala/tools/nsc/ast/DocComments.scala doesn't mention `@link`. – VonC Jun 08 '12 at 17:59
@VonC Yes, now I know Scaladoc uses [[fullyQualifiedName]] instead of {@link}. – Martin Konicek Jun 15 '12 at 09:03
@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}` – VonC Jun 15 '12 at 11:06

score 7 · Answer 2 · edited Sep 25 '11 at 07:02

7

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.

edited Sep 25 '11 at 07:02

wchargin

15,589
12
71
110

answered Sep 25 '11 at 02:55

Keith Pinson

1,725
1
14
17

Thanks very much, this is a fantastic resource. – David J. Sep 25 '11 at 16:29
I noticed that you frequently used `/*#! scaladoc */` in your source. Is this important? – David J. Sep 25 '11 at 16:30
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. – Keith Pinson Sep 28 '11 at 04:46

score 4 · Answer 3 · edited Jun 15 '12 at 09:13

4

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.

edited Jun 15 '12 at 09:13

Martin Konicek

39,126
20
90
98

answered Sep 25 '11 at 02:12

David J.

31,569
22
122
174

I'd recommend this resource over all the others as well. – Martin Konicek Jun 15 '12 at 09:14

Martin Konicek · Answer 4 · 2012-06-21T17:39:45.270

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()}).

score 0 · Answer 5 · answered Dec 25 '15 at 18:23

0

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.

answered Dec 25 '15 at 18:23

pvillela

553
1
6
10

Where to find tutorials for scaladoc 2?

5 Answers5