[RFR] Add @​name annotation

src/annotation/annotations/index.js

@@ -8,6 +8,7 @@ module.exports = [
   require('./group.js'),
   require('./ignore.js'),
   require('./link.js'),
+  require('./name.js'),
   require('./output.js'),
   require('./parameter.js'),
   require('./property.js'),

src/annotation/annotations/name.js

@@ -0,0 +1,20 @@
+export default function access() {
+  return {
+    name: 'name',
+
+    parse(text) {
+      return text.trim();
+    },
+
+    // Abuse the autofill feature to rewrite the `item.context`
+    autofill(item){
+      if (item.name) {
+        item.context.name = item.name;
+        // Cleanup
+        delete item.name;
+      }
+    },
+
+    multiple: false
+  };
+}

test/annotations/name.test.js

@@ -0,0 +1,14 @@
+'use strict';
+
+var assert = require('assert');
+
+describe('#name', function () {
+  var name = (new (require('../../dist/annotation'))()).list.name;
+
+  it('should return the trimmed string', function () {
+    assert.equal(name.parse('   '), '');
+    assert.equal(name.parse('   '), '');
+    assert.equal(name.parse('\ntest\t'), 'test');
+    assert.equal(name.parse('\nte\nst\t'), 'te\nst');
+  });
+});

test/data/expected.json

@@ -600,5 +600,29 @@
       "path": "test.scss",
       "name": "test.scss"
     }
+  },
+  {
+    "description": "This is a test placeholder aiming at testing:\n- `@name`\n",
+    "commentRange": {
+      "start": 175,
+      "end": 177
+    },
+    "context": {
+      "type": "placeholder",
+      "name": "placeholder-[blue,green,red]",
+      "code": "",
+      "line": {
+        "start": 179,
+        "end": 179
+      }
+    },
+    "group": [
+      "test"
+    ],
+    "access": "private",
+    "file": {
+      "path": "test.scss",
+      "name": "test.scss"
+    }
   }
 ]

test/data/test.scss

@@ -171,3 +171,9 @@ $variable-specific-test: ();
 /// @alias should-warn
 
 @function alias-test-should-warn() {}
+
+/// This is a test placeholder aiming at testing:
+/// - `@name`
+/// @name placeholder-[blue,green,red]
+
+%placeholder-#{$color} {}