I looked at the Akka framework while going through Venkat’s book. One things I did not like about Akka is that it does not take too long until you work with Scala APIs besides Akka. Many of them do not have javadocs. So you have to read scaladoc to use them. It is not that hard, but it just seems like every time I look at scaladoc I have to learn it from scratch again.
So in this post I will try to explain scaladoc for Java developers.
Look at the javadoc for the Akka class UntypedActor, and then the scaladoc for UntypedActor. In the javadoc, we can see that akka.actor.UntypedActor inherits from java.lang.Object. In Scala, it inherits from scala.Any, which seems to be the Scala equivalent of java.lang.Object.
The Java class implements the akka.actor.Actor interface. The Scala class implements from the trait akka.actor.Actor. I do not know how a trait is different from a class or an interface. In the scaladoc, Actor and Any are pointed out at the same place in the scaladoc. In the javadoc, the interface and the parent class are in different spots in the file.
The first method in the javadoc is getContext(), which returns an UntypedActorContext. The methods are in a table, and the return values are all on the left side of the table.
getContext is not the first method listed in the scaladoc. I do not know exactly what “Type Members” are. The getContext() method is listed in the “Concrete Value Members” section. The section for getContext() is listed like this:
def getContext(): UntypedActorContext
The javadoc has this:
UntypedActorContext getContext()
The difference is that in scaladoc the return value is listed after the name of the function. I am not too clear what “def” means.
Let’s look at a method that takes an argument. Let’s look at “onReceive”. This method is abstract.
Here is the method in the javadoc:
abstract void onReceive(java.lang.Object message)
Here is the method in the scaladoc:
abstract def onReceive(message: Any): Unit
I think that “Unit” in Scala is like returning void in Java. In both cases, the methods take a parameter named “message”. In the javadoc, we see the parameter’s type and then its name. In the scaladoc, we see the parameter’s name, and then its type.
Lastly, I will look at a method that takes a couple of parameters for review. The method is preRestart().
Here is the method in javadoc:
void preRestart(java.lang.Throwable reason, scala.Option<java.lang.Object> message)
Here is the method in scaladoc:
def preRestart(reason: Throwable, message: Option[Any]): Unit
Every time I mention Scala on this blog, I mention that I do not like it. I thought I should mention it in this post just for consistency.
Image from an 11th century manuscript housed at Bibliotheken Schaffhausen (Wikipedia page here), image from e-Codices, assumed allowed under Fair Use.