Description
Yesterday, I was using ScalaDoc for real for the first time, and I had to figure some aspects of the syntax and semantics out by experiments or looking at random Scala sources. @Blaisorblade convinced me I should report the missing bits of information somewhere so they can be fixed :) I hope this is the right place, please direct me to the right place if not.
To learn about ScalaDoc, I started reading http://docs.scala-lang.org/style/scaladoc.html and then followed the link to https://wiki.scala-lang.org/display/SW/Writing+Documentation. Maybe there is something else I should have read?
I remember having trouble to figure the following bits out:
- to link to companion objects, use a
$at the right place - to use your own link text, put after the link target in the double brackets
- bullet lists can nest
- the scope of
@defineis to the end of the doc comment or to the next@define - macros are inherited from super classes to objects, but docs are not
I'm also confused about how to best document a hierarchy of case classes with some intermediate traits. I would like for readers to look at the whole hierarchy at once, not at each case class separately. But I also don't want to repeat the hierarchy manually because I plan to extend it and I'm afraid I'll not keep the docs up-to-date. The style guide tells me to document each case class separately, but I didn't see anyhing about how to document the whole hierarchy.