5

I would like to create ScalaDoc entries to every val and def of my class. The problem is that the vals lie inside a pattern definition, and don't know how to use the /** */ syntax.

Example:

class C(id: String) {
   val (part1, part2) = {
         .....
         (expr1, expr2)
   }
}

How do I document part1 and part2?

I've read before asking this documentation about ScalaDoc.

david.perez
  • 6,090
  • 4
  • 34
  • 57
  • 1
    You can do `private val parts = { ... }; /** ... */ val part1 = parts._1; /** ... */ val part2 = parts._2;`. –  Jul 24 '14 at 12:26
  • Good one, I was going to say: "You can document the function that produces the tuple (extract that code into a function if needed)" but this works only for internal developer documentation where vals are private. I prefer @rightfold solution unless there is some special scaladoc thing for that. – yǝsʞǝla Jul 24 '14 at 16:44

1 Answers1

3

It should be

  val (
    /** Part one. */
    x,
    /** Part two. */
    y
  ) = (1, 2)

but for a flawed heuristic

/** To prevent doc comments attached to expressions from leaking out of scope
 *  onto the next documentable entity, they are discarded upon passing a right
 *  brace, bracket, or parenthesis.
 */
def discardDocBuffer(): Unit = ()

Under -Xlint you will see

[warn] /home/apm/goofy/src/main/scala/docked.scala:10: discarding unmoored doc comment
[warn]     /** Part two. */
[warn]     ^

Maybe the heuristic could be improved to discard only if no doc is discovered on the enclosing entity.

som-snytt
  • 39,429
  • 2
  • 47
  • 129