Normalize description in annotations

[KittyGiraudel]

@returns:

/**
 * @returns {type} Description of the return statement
 */

@param:

/**
 * @param {type} $name - description
 */

Incoming @requires:

/**
 * @requires {type} name - Description of the return statement
 */

First, the hyphen:

• either we make it mandatory;
• or we remove it;
• or we make it optional.

Second, we make all those annotations behave the same by following the same rule. Curently, hyphen doesn't exist in @returns, is mandatory on @param and is about to be added as optional to @requires. Nope.

So, how do we do?

Edit: I'm tagging this for v1. It's not much, but we need to settle things down now.

[pascalduez]

The hyphen really helps to make things clearer when it comes to @param or @requires, it marks the separation between name or $name and the description.
For @returns it's a bit different since the curly braces are already playing this role somehow.

So hyphen mandatory for @param and @requries yes.
For @returns maybe not, but allowed ?

[KittyGiraudel]

So hyphen mandatory for @param and @requries yes.
For @returns maybe not, but allowed ?

I am worried about having different approaches for the same feature (specifying a description). All three annotations, and all incoming annotations allowing a description should probably behave the same.

I think having the hyphen not only helps making things easier to read as Pascal said, but also clearly defines where the description starts. For now, everything that comes before a description is very explicit: either a name (single word, no space) or a type (braces). But some day, we might have a parameter accepting spaces right before a description. Then we'll be forced to have an hyphen.

So should we make it mandatory right now just to be future proof?

Now regarding @returns, as Pascal said, it is not a big deal to omit it since there are the braces that clearly delemit the two parameters. Meanwhile, this kind of break the above rule. What if we made it mandatory as well? That might look weird though.

I don't know.

[pascalduez]

/**
 * @returns {Map} - A map containing some keys and values, yes crazy.
 */

Well it's okay, looks a bit redundant but we can live with this I guess.

[valeriangalliat]

I don't remember to ever seen this hyphen thing in other documentation formats... while I don't dislike it, I don't think it should be mandatory.

So I'd go for optional hyphen everywhere.

[KittyGiraudel]

So I'd go for optional hyphen everywhere.

Consider:

/**
 * @annotation parameter description
 */

Now what if parameter can contain spaces?

[valeriangalliat]

Parameter cannot contain spaces.

[KittyGiraudel]

Why?

[valeriangalliat]

I don't see any kind of annotation for software documentation where it would be necessary to have spaces in the parameter before the description. It's usualy a function or variable identifier which can't contain spaces.

If it's really necessary, the hyphen is required to distinguish the parameter from the description (but what if the parameter can contain hyphens?), that's why I propose to make it optional.

[KittyGiraudel]

If it's really necessary, the hyphen is required to distinguish the parameter from the description (but what if the parameter can contain hyphens?), that's why I propose to make it optional.

Fair point.

Let's go with optional everywhere.

[FWeinb]

I would say that this should be dynamic enough http://www.regexr.com/394l2

[KittyGiraudel]

Okay.