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.

1. Scaladoc for reflection
(new features in 2.10)
Vlad Ureche
19th of July 2012

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 ...
}

4. @inheritdoc
Comment inheritance

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

10. @template / @documentable
trait Base {
/** Type represents a scala type.
* @template
*/
type Type < : TypeBase
}

11. @template / @documentable
trait Base {
/** Type represents a scala type.
* @template
*/
type Type < : TypeBase
}

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.

15. Groups
Au revoir, api/extractors!

16. Skip packages
● Do we want to expose scala.reflect.internal?
scaladoc -skip-packages scala.reflect.internal:<pack2>:...
<scaladoc ...
skipPackages="scala.reflect.internal"/>

17. Links
● link anything in the scaladoc pages
– classes, traits, objects, types
– methods, values, overloeded methods

18. Links
scala . collection . List # apply

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)