Why @description?

[Broofa]

Denis, the @description tag is confusing to me. E.g. currently I can
do this ...

/**
* (... really long, rich description of project ...)
*
* @project (... project title...)
* @description (... brief description ...)
*/

There are three descriptive properties here: the comment text, the
@project title, and the @description. I think this is one too many.

Specifically, the @description tag seems a bit superflous. jGD should
use the @project title where it needs to show a short description,
otherwise it should use the "really long, rich description" I provide
in as the comment text.

Can we remove the @description tag?
- It leads to confusion as to where a person should put the project
description.
- It's just another tag cluttering up the tag namespace
- It's redundant with the @project title (i.e. aren't "title" and
brief description" pretty much the same thing here?)
- It may be misused elsewhere, for example people may try to apply
it to other types of comments - @functions, @vars, and whatnot, when
they should just be supplying regular comment text.

[denis.r...@gmail.com]

It is meant to be a short summary of the project. Kind of similar you
get from the first sentence of function/class/etc description.

Just title is not quite sufficient. Just look at JavaDoc for JDK -
you've got title "Java(tm) Platform, Standard Edition 6", you've got
summary "This document is the API specification for version 6 of the
Java(tm) Platform, Standard Edition." and long description down below.