I found docs for the #define scaladoc macro but they don't go into any depth.
What I'm trying to do is write documentation in a base class/trait in a generic way, with #defined variables so that the wording in the generated docs for the subclasses makes sense.
I've distilled this down to an example of something I would have expected to work, but doesn't:
/**
* #define Word base-word
*/
class DocTestBase {
/** Does a $Word
*
* #return
*/
def foo = 1
}
/**
* #define Word subclass word!
*/
class DocTestSubclass extends DocTestBase
With the above, I'd expect the generated documentation for DocTestSubclass#foo to say "Does a subclass word!", but as you can see below, it doesn't.
FWIW I also tried this on Scala 2.12 but the result is the same.
How do I get this to work as I expect? Is this a bug in scaladoc?
Related
In Scala, if I have an Enumeration like this:
package myPackage.letters
object Alphabet extends Enumeration {
val A: Value = Value("A")
val B: Value = Value("B")
val C: Value = Value("C")
}
Now, I want to write a ScalaDoc for a method in another package and reference the values of my Enum like this:
/**
* Here, I want to reference my enum:
* this works: [[myPackage.letters.Alphabet]]
* this does not: [[myPackage.letters.Alphabet.A]]
*/
def myMethod = {}
Is this maybe an IntelliJ specific problem? Anyway I cannot seem to figure out how to correctly reference enum values or if it is even possible.
I figured it out: [[myPackage.letters.Alphabet#A]]
I came across this following piece of code which has a trait like this and has some methods defined in it:
trait TypeTaggedTrait[Self] { self: Self =>
/**
* The representation of this class's type at a value level.
*
* Useful for regaining generic type information in runtime when it has been lost (e.g. in actor communication).
*/
val selfTypeTag: TypeTag[Self]
/**
* Compare the given type to the type of this class
*
* Useful for regaining generic type information in runtime when it has been lost (e.g. in actor communication).
*
* #return true if the types match and false otherwise
*/
def hasType[Other: TypeTag]: Boolean =
typeOf[Other] =:= selfTypeTag.tpe
/**
* Attempt to cast this value to the given type.
*
* If the types match, the casted version is returned. Otherwise, empty value is returned.
*
* Useful for regaining generic type information in runtime when it has been lost (e.g. in actor communication).
*
* #return casted version wrapped in `Some` if the cast succeeds, and otherwise `None`
*/
def cast[Other: TypeTag]: Option[Other] =
if (hasType[Other])
Some(this.asInstanceOf[Other])
else
None
}
abstract class TypeTagged[Self: TypeTag] extends TypeTaggedTrait[Self] { self: Self =>
val selfTypeTag: TypeTag[Self] = typeTag[Self]
}
I then tried to implement this trait like this:
case class MyCase(str: String, i: Int)
final class MyTypeTagged[MyCase] extends TypeTagged[MyCase] {
....
....
}
Obviously it fails compilation with the following message as seen in the screen shot.
Can anyone please help me with what is happening? If I give the whole MyTypeTagged[MyCase], it works. How should I interpret this? It is expecting the enclosing type as well. How should I interpret this?
Is there a way to add a new ScalaDoc annotation? Specifically, I'd like to define #business annotation as an extension of #note.
This, obviously, should be able to behave as the #note:
/**
* #business A business description of the item.
*/
def definition: _ = ???
In my Node.js project, I have normal class definitions like:
/**
* My awesome class.
* #constructor
*/
var MyClass = function MyClass() {}
And in another file I require it like:
var MyClass = require('./myclass.js').MyClass;
But sometimes JSDoc finds the require statement and only documents MyClass as a global variable. How to make JSDoc always document the class definition and ignore the variables defined in require statements?
trait App extends DelayedInit {
//...
private val initCode = new ListBuffer[() => Unit]
/** The init hook. This saves all initialization code for execution within `main`.
* This method is normally never called directly from user code.
* Instead it is called as compiler-generated code for those classes and objects
* (but not traits) that inherit from the `DelayedInit` trait and that do not
* themselves define a `delayedInit` method.
* #param body the initialization code to be stored for later execution
*/
override def delayedInit(body: => Unit) {
initCode += (() => body)
}
//...
}
object CircuitMain extends App {
// You can write tests either here, or better in the test class CircuitSuite.
Circuit.andGateExample //line in question ?
}
Related Post why-if-i-extend-the-app-trait-in-scala-i-override-the-main-method
I can see that in the comment it is saying it will be called by compiler generated code.
and from the related post, it is saying that the scala compiler will do special things about DelayedInit, what made this DelayedInit trait so special ? is it language related feature? or we can do similar things to other traits as well ? if yes, how to do that.
Was pondering this myself the other day...
Yes, it's a language specific feature - check Section 5.1 "Delayed Initializaton" in the Scala Language Specification:
http://www.scala-lang.org/docu/files/ScalaReference.pdf
You can also confirm this checking out the compiler source code:
https://github.com/scala/scala/blob/946b76ad8b31b1fd74e2f8e1972c4a9159ac690a/src/reflect/scala/reflect/internal/StdNames.scala
// Compiler utilized names
...
val delayedInit: NameType = "delayedInit"
val delayedInitArg: NameType = "delayedInit$body"
And also:
https://github.com/scala/scala/blob/96df73d994097e3318d003ddef00194b711289a3/src/reflect/scala/reflect/internal/Definitions.scala
// classes with special meanings
lazy val StringAddClass = requiredClass[scala.runtime.StringAdd]
lazy val ScalaNumberClass = requiredClass[scala.math.ScalaNumber]
lazy val TraitSetterAnnotationClass = requiredClass[scala.runtime.TraitSetter]
lazy val DelayedInitClass = requiredClass[scala.DelayedInit]
def delayedInitMethod = getMemberMethod(DelayedInitClass, nme.delayedInit)