Clarifying recommendation for doc comments.

BUG=https://github.com/dart-lang/www.dartlang.org/issues/1201
R=kathyw@google.com

Review URL: https://codereview.appspot.com//187450043