scala/scala — pull request #2872 by jamesward (2013-08-24 16:14:01+00:00)
Title: add scaladoc canonical name

One of the challenges I've had learning and using Scala is the use of symbol methods like `++:` because they lack a name. Without a name symbols are hard to comprehend, search for, and talk about. I find it is hard to mentally parse code that uses symbols that I don't have a name for. Also, trying to search StackOverflow or DuckDuckGo for symbols is usually impossible or difficult. An attempt was made to use a `Google Tag for Scala` (gt4s) that would provide a searchable name for symbols. However this doesn't seem to have caught on possibly because the tag names were derived (lacking meaning) and because the ScalaDoc UI didn't plainly expose them.

This pull request tries a different approach by adding a new ScalaDoc tag, `@canonical` which allows symbol authors to provide a canonical name for a symbol. That name is then displayed in the ScalaDoc signature:
![scaladoc-canonical](https://f.cloud.github.com/assets/65043/1020999/b4bc4b66-0cd7-11e3-97fe-df611a5ced3b.png)

This pull request includes two symbol names in `GenTraversableLike.scala` which are likely the wrong names but included as examples.