Scaladoc for reflection

2,024 views
1,875 views

Published on

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.

Published in: Technology, Sports
1 Comment
3 Likes
Statistics
Notes
No Downloads
Views
Total views
2,024
On SlideShare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
0
Comments
1
Likes
3
Embeds 0
No embeds

No notes for slide

Scaladoc for reflection

  1. 1. Scaladoc for reflection (new features in 2.10) Vlad Ureche 19th of July 2012
  2. 2. Outline● 2.10 scaladoc new features – @inheritdoc – Diagrams – @template (or @documentable) – Groups – Skip packages – Links
  3. 3. @inheritdoctrait Base { /** Type represents a scala type. */ type Type < : TypeBase}trait Api { /** @inheritdoc * * More details added later. */ abstract class Type ...}
  4. 4. @inheritdoc Comment inheritance
  5. 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. 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. 7. Diagrams/** Description of the base trait * @contentDiagram * @inheritanceDiagram hideDiagram */trait Base { /** Type represents a scala type. */ type Type < : TypeBase}
  8. 8. Diagrams Try clicking Type. Oh noes, it doesnt work! Type is an abstract type
  9. 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. 10. @template / @documentabletrait Base { /** Type represents a scala type. * @template */ type Type < : TypeBase}
  11. 11. @template / @documentabletrait Base { /** Type represents a scala type. * @template */ type Type < : TypeBase}
  12. 12. @template Also finds values and treats them as companion objectsCLICK
  13. 13. Groups● scala.reflect.api.Types defines 46 types – useful types (Type, TypeRef, …) – classes that give the methods (TypeRefApi, ...) – extractors (TypeRefExtractor, …)● wouldnt it be nice to group them?
  14. 14. Groupspackage scala.reflectpackage 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. 15. Groups Au revoir, api/extractors!
  16. 16. Skip packages● Do we want to expose scala.reflect.internal? scaladoc -skip-packages scala.reflect.internal:<pack2>:... <scaladoc ... skipPackages="scala.reflect.internal"/>
  17. 17. Links● link anything in the scaladoc pages – classes, traits, objects, types – methods, values, overloeded methods
  18. 18. Linksscala . collection . List # apply
  19. 19. Linksscala . collection . List # unapply Separators? Both # and . are valid separators
  20. 20. Linksscala . 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. 21. Linksscala . collection . List # unapply Overloaded? Use full signature followed by *. – the signature generated by scaladoc
  22. 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)

×