An internal presesentation of the new features in the scaladoc tool in the 2.10 release of the Scala programming language compiler.
It explains new features and gives usage examples tailored for documenting the new reflection part of the Scala library.
2. Outline
● 2.10 scaladoc new features
– @inheritdoc
– Diagrams
– @template (or @documentable)
– Groups
– Skip packages
– Links
3. @inheritdoc
trait Base {
/** Type represents a scala type. */
type Type < : TypeBase
}
trait Api {
/** @inheritdoc
*
* More details added later. */
abstract class Type ...
}
5. Diagrams
● Two types
– inheritance diagrams
● contain superclasses, subclasses and implicits
● generated by default for classes and traits
– content diagrams
● classes/traits/objects contained
● generated by default for packages and objects
● Oh noes
– trait Base will only get an inheritance diagram, no
contents :((
6. Diagrams
● You can override default behavior
– @inheritanceDiagram
– @contentDiagram
– add the annotation to get the diagram
– add hideDiagram to get rid of the diagram
– undesirable node? hideNodes "*internal*"
– undesirable edge? hideEdges("*A" -> "*B")
7. Diagrams
/** Description of the base trait
* @contentDiagram
* @inheritanceDiagram hideDiagram
*/
trait Base {
/** Type represents a scala type. */
type Type < : TypeBase
}
8. Diagrams
Try clicking Type.
Oh noes, it doesn't work!
Type is an abstract type
9. @template / @documentable
● Add this to your {abstract,alias} type
– to get a page for the type
– to get a clickable node in the template
12. @template
Also finds values and treats
them as companion objects
CLICK
13. Groups
● scala.reflect.api.Types defines 46 types
– useful types (Type, TypeRef, …)
– classes that give the methods (TypeRefApi, ...)
– extractors (TypeRefExtractor, …)
● wouldn't it be nice to group them?
14. Groups
package scala.reflect
package api
/**
* @groupdesc Types These entities represent types
* <longer description follows>
*/
trait Types extends base.Types { self: Universe =>
/** @group Types */
override type TypeRef >: Null <: Type with TypeRefApi
If you set the group,
all overrides inherit that.
19. Links
scala . collection . List # unapply
Separators?
Both # and . are valid separators
20. Links
scala . collection . List # unapply
Class List or object List?
– backtracking (only the object has method apply)
– disambiguation
– List$ points to the object
– List! points to the class
21. Links
scala . collection . List # unapply
Overloaded? Use full signature followed by *.
– the signature generated by scaladoc
22. Thank you!
● 2.10 scaladoc new features
– @inheritdoc
– Diagrams
– @template / @documentable
– Groups
– Skip packages
– Links
Everything is in
pull request 925 on github:
https://github.com/scala/scala/pull/925
(and a lot more)