Improvements to the ScalaDoc checker

The IntelliJ IDEA plugin showed the need for better messages and better parsing of the ScalaDoc block. This PR addresses those areas, for example, the previous version would accept

```scala
/** 
 * Foo
 * @param a
 * @return nothing useful
 */
def foo(a: Int): Unit = ()
```

as valid ScalaDoc, thinking that the text of the ``@param a`` is ``@return nothing useful``.