Normalize description in annotations #81

Closed
HugoGiraudel opened this Issue Jul 9, 2014 · 11 comments

Comments

Projects
None yet
4 participants
@HugoGiraudel
Member

HugoGiraudel commented Jul 9, 2014

@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.

@HugoGiraudel HugoGiraudel added this to the 1.0 milestone Jul 9, 2014

@HugoGiraudel HugoGiraudel added Bug and removed Bug labels Jul 9, 2014

@pascalduez

This comment has been minimized.

Show comment
Hide comment
@pascalduez

pascalduez Jul 9, 2014

Member

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 ?

Member

pascalduez commented Jul 9, 2014

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 ?

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Jul 9, 2014

Member

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.

Member

HugoGiraudel commented Jul 9, 2014

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

This comment has been minimized.

Show comment
Hide comment
@pascalduez

pascalduez Jul 9, 2014

Member
/**
 * @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.

Member

pascalduez commented Jul 9, 2014

/**
 * @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.

@HugoGiraudel HugoGiraudel modified the milestone: 1.0 Jul 9, 2014

@valeriangalliat

This comment has been minimized.

Show comment
Hide comment
@valeriangalliat

valeriangalliat Jul 9, 2014

Member

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.

Member

valeriangalliat commented Jul 9, 2014

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.

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Jul 9, 2014

Member

So I'd go for optional hyphen everywhere.

Consider:

/**
 * @annotation parameter description
 */

Now what if parameter can contain spaces?

Member

HugoGiraudel commented Jul 9, 2014

So I'd go for optional hyphen everywhere.

Consider:

/**
 * @annotation parameter description
 */

Now what if parameter can contain spaces?

@valeriangalliat

This comment has been minimized.

Show comment
Hide comment
@valeriangalliat

valeriangalliat Jul 9, 2014

Member

Parameter cannot contain spaces.

Member

valeriangalliat commented Jul 9, 2014

Parameter cannot contain spaces.

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
Member

HugoGiraudel commented Jul 9, 2014

Why?

@valeriangalliat

This comment has been minimized.

Show comment
Hide comment
@valeriangalliat

valeriangalliat Jul 9, 2014

Member

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.

Member

valeriangalliat commented Jul 9, 2014

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.

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Jul 9, 2014

Member

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.

Member

HugoGiraudel commented Jul 9, 2014

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

This comment has been minimized.

Show comment
Hide comment
@FWeinb

FWeinb Jul 9, 2014

Member

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

Member

FWeinb commented Jul 9, 2014

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

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Jul 9, 2014

Member

Okay.

Member

HugoGiraudel commented Jul 9, 2014

Okay.

@FWeinb FWeinb closed this in 786a584 Jul 9, 2014

FWeinb added a commit that referenced this issue Jul 9, 2014

valeriangalliat added a commit that referenced this issue Jan 9, 2015

Do not try to safe-wipe when unknown or unclear `src`
* When it's a string, we use it as parent, stripping eventual glob
  patterns.
* When it's an array, or we don't have any `src` because of streaming,
  we don't check anything.

---

* Related: #81
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment