Describe ScalaDoc syntax and semantics

[Toxaris]

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 @define is 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.

[SethTisue]

@VladUreche there aren't other authoring docs @Toxaris missed, are there?

[VladUreche]

I guess this old presentation may help as well: http://www.slideshare.net/VladUreche/scaladoc-reflection. I also gave some notes I had to @janekdb hoping he will publish them, but they are very crappy.

I think someone should make a push to document Scaladoc, since it has a lot of nice features, but I just don't have the time to take care of this. On the other hand, I'd be glad to help anyone who steps up by answering any question they may have.

[janekdb]

I have been making glacial progress on https://github.com/scala/scala.github.com/pull/521 and have the links from Vlad to use. I'll have a go at picking up the pace a bit.

[SethTisue]

another old ticket: https://github.com/scala/scala-lang/pull/394

[dragos]

Yeah, this is quite annoying, I'll give it a try. I often need to google for that forgotten wiki page. Where should this go, docs.scala-lang or scala-lang.org? I'm guessing the former.

[heathermiller]

That would be awesome, thanks Iuli. It should go to docs.scala-lang

[janekdb]

Shamefacedly I have to reveal that I redirected my energies into Chapter 8 of https://www.amazon.co.uk/Professional-Scala-Janek-Bogucki/dp/1119267226 toward the end of last year.

Don't be deceived by the one-star review - over the course of 45 pages everything I could find about Scaladoc is surveyed and explained including quite a lot of hitherto undocumented capability. I believe I consulted the forgotten wiki page when putting this together.

At the least it could be used as a checklist for future documentation efforts.

[dragos]

Ok, there is already a page about scaladoc for library authors. I'll check if there are missing bits that appear only on the wiki page, but it looks fairly complete already.

[janekdb]

Shamefacedly I have to reveal that I redirected my energies into Chapter 8 of https://www.amazon.co.uk/Professional-Scala-Janek-Bogucki/dp/1119267226 toward the end of last year.

Don't be deceived by the one-star review - over the course of 45 pages everything I could find about Scaladoc is surveyed and explained including quite a lot of hitherto undocumented capability. I believe I consulted the forgotten wiki page when putting this together.

At the least it could be used as a checklist for future documentation efforts.

On 21 October 2016 at 14:13, Heather Miller notifications@github.com wrote:

That would be awesome, thanks Iuli. It should go to docs.scala-lang

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/scala/scala.github.com/issues/526#issuecomment-255372909, or mute the thread https://github.com/notifications/unsubscribe-auth/ABEmD0zWou7IuvwLmWpFSMlGcoURFFK-ks5q2LpdgaJpZM4IZp3i .

[SethTisue]

it sounds like there are multiple sources of documentation and it's easy to find one and think it's all there is, when actually there's more.

ideally maybe there'd be some big merge, but perhaps in the meantime someone would like to do a more modest PR (or group of PRs, if multiple repos are involved) that just adds cross-links? (including Janek's thing, I don't see a reason not to link to that too)

[xolve]

There are two important pages Scaladoc Style Guide and Scaladoc For Library Authors. These seem like quick tutorials than reference documents. e.g. While browsing Scale code I see sytnax which I cannot find.

Scaladoc Style Guide suggests Use the wiki-style syntax instead of HTML wherever possible.. What wiki-style means here is not clear.

[laughedelic]

@xolve you can find that wiki-syntax in the second document in the Markup section.

[xolve]

Thank you @laughedelic this is very helpful 👍

[SethTisue]

another piece of doc: https://www.scala-lang.org/blog/2018/10/04/scaladoc-tables.html