Scaladoc swallowed @throws and @note tags

Question

When creating a Scala documentation I also use the @throws and @note tags like documented here (Scaladoc Wiki - Tags and Annotations).

Unfortunately I can't find these in the generated Scaladoc.

Do one have to set certain switches, consider something specific or is this a known problem?

BTW: using the scaladoc Ant task of Scala 2.9.0.1 that issues no warning too.

EDIT: BTW2 and to clarify: I do not mean the @throws annotation

@throws(classOf[RuntimeException])
def dispatch: Nothing = throw new RuntimeException

which is documented in the annotations section of this def but the @throws tag for Scaladoc like

/** @throws RuntimeException
 */
def dispatch: Nothing = throw new RuntimeException

Venicevenin

Which version of Scala are you using? The support for @throws seems fairly recent (May/June 2011): github.com/scala/scala/pull/23 – Alethiaaletta

Did you tried with 2.9.1 final? – Alethiaaletta

@throws does not get ignored with 2.9.0.1. It works with my version of scaladoc. At least, they appear in the Annotations section. – Mazzola

@Alethiaaletta I've just tried 2.9.1 final (with scaladoc from command line) => it seems to be the same. But the tags @throws and @note are well known by the tool - because if one writes the tag incorrectly (eg @notes), then there is indeed a warning: Tag '@notes' is not recognised. – Venicevenin

@binuWADa: ok, then following Matthew's comment, is it possible that those tags are taken into account, but that you are looking for them in the wrong place? Or that they are somehow hidden by the stylesheet? – Alethiaaletta

@Alethiaaletta and Matthew Farwell: answered with an edit - I think @throws annotation and @throws tag are not exactly the same thing. – Venicevenin

Yes, you're right, they are different things. I misunderstood the question, and I'm getting the same behaviour as you. – Mazzola

Answer 1

I added support for @note half a year ago.

If you have a look here, it seems to work correctly: scala.util.matching.Regex

The other things is the @throws ScalaDoc tag. Actually I'm thinking about removing support for it in favor of the @throws annotation, which is supported, because I can't see any use case where one would prefer the ScalaDoc tag to the annotation.

If you have a real need please let me no, let me know!

Edit: Mhhh. Looking at scala.Array it actually looks like it is the other way around...

Mirianmirielle

An use case would be a more detailed explanation of when (why, under what condition) the exception is thrown, e.g. @throws RuntimeException when something happen which is inpossible with the @throws annotation, that only tells you that this exception could be thrown. – Venicevenin

I'm just keeping an eye on your link and I must say wow - the syntax highlighting from the nightly build Scaladoc code sections looks so great! That wasn't the issue, but had to be said ;-) – Venicevenin

Did the change actually make it into 2.9.1? I can't see 25042 in scala-lang.org/node/10743 – Mazzola

@binuWADa: What about having something like @throws(clazz: Class[_], reason: String = "")? Would that be usable for you? – Mirianmirielle

@soc: Of course, that would fulfill its purpose. But for my interest: What is the @throws annotation good? Or more precisely: What tool (except Scaladoc) could use its information (perhaps without reason)? – Venicevenin

Answer 2

This is a combination of a bug and something that hasn't made it into a release yet.

@note does not work, this is a known bug, see @todo, @note and @example don't work?

@throws was only added recently, see this pull request from Simon Ochsenreither, which was merged in July 2011. This hasn't yet made it into a release, 2.9.0.1 was released in May 2011, and 2.9.1 was started in July 2011.

Mazzola

@Matthew Farwell: Does this mean that @throws could be available with next version > 2.9.1? – Venicevenin

@Venicevenin I would imagine so. – Mazzola