refactor(core): simplify decorators

Every decorator now is made of the following:
- a function that can be used
as a decorator or as a constructor. This function
also can be used for `instanceof` checks.
- a type for this function (callable and newable)
- a type that describes the shape of the data
  that the user needs to pass to the decorator
  as well as the instance of the metadata

The docs for decorators live at the followig places
so that IDEs can discover them correctly:
- General description of the decorator is placed on the
  `...Decorator` interface on the callable function
  definition
- Property descriptions are placed on the interface
  that describes the metadata produces by the decorator

modules/@angular/core/test/util/decorators_spec.ts

@@ -13,44 +13,37 @@ import {beforeEach, ddescribe, describe, expect, iit, inject, it, xit} from '@an
 
 import {global} from '../../src/facade/lang';
 
-class TestAnnotation {
-  constructor(public arg: any) {}
-}
-
-class TerminalAnnotation {
-  terminal = true;
-}
-
 class DecoratedParent {}
 class DecoratedChild extends DecoratedParent {}
 
 export function main() {
   var Reflect = global.Reflect;
 
-  var TerminalDecorator = makeDecorator(TerminalAnnotation);
-  var TestDecorator = makeDecorator(TestAnnotation, (fn: any) => fn.Terminal = TerminalDecorator);
+  var TerminalDecorator = makeDecorator({terminal: true});
+  var TestDecorator =
+      makeDecorator({marker: undefined}, Object, (fn: any) => fn.Terminal = TerminalDecorator);
 
   describe('decorators', () => {
     it('should invoke as decorator', () => {
       function Type() {}
       TestDecorator({marker: 'WORKS'})(Type);
       var annotations = Reflect.getMetadata('annotations', Type);
-      expect(annotations[0].arg.marker).toEqual('WORKS');
+      expect(annotations[0].marker).toEqual('WORKS');
     });
 
     it('should invoke as new', () => {
       var annotation = new (<any>TestDecorator)({marker: 'WORKS'});
-      expect(annotation instanceof TestAnnotation).toEqual(true);
-      expect(annotation.arg.marker).toEqual('WORKS');
+      expect(annotation instanceof TestDecorator).toEqual(true);
+      expect(annotation.marker).toEqual('WORKS');
     });
 
     it('should invoke as chain', () => {
       var chain: any = TestDecorator({marker: 'WORKS'});
       expect(typeof chain.Terminal).toEqual('function');
       chain = chain.Terminal();
-      expect(chain.annotations[0] instanceof TestAnnotation).toEqual(true);
-      expect(chain.annotations[0].arg.marker).toEqual('WORKS');
-      expect(chain.annotations[1] instanceof TerminalAnnotation).toEqual(true);
+      expect(chain.annotations[0] instanceof TestDecorator).toEqual(true);
+      expect(chain.annotations[0].marker).toEqual('WORKS');
+      expect(chain.annotations[1] instanceof TerminalDecorator).toEqual(true);
     });
 
     it('should not apply decorators from the prototype chain', function() {
@@ -59,13 +52,13 @@ export function main() {
 
       var annotations = Reflect.getOwnMetadata('annotations', DecoratedChild);
       expect(annotations.length).toBe(1);
-      expect(annotations[0].arg.marker).toEqual('child');
+      expect(annotations[0].marker).toEqual('child');
     });
 
     describe('Class', () => {
       it('should create a class', () => {
         var i0: any /** TODO #9100 */, i1: any /** TODO #9100 */;
-        var MyClass = (<any>TestDecorator('test-works')).Class(<any>{
+        var MyClass = (<any>TestDecorator({marker: 'test-works'})).Class(<any>{
           extends: Class(<any>{
             constructor: function() {},
             extendWorks: function() { return 'extend ' + this.arg; }
@@ -89,7 +82,7 @@ export function main() {
         expect(proto.extends).toEqual(undefined);
         expect(proto.prototype).toEqual(undefined);
 
-        expect(reflector.annotations(MyClass)[0].arg).toEqual('test-works');
+        expect(reflector.annotations(MyClass)[0].marker).toEqual('test-works');
       });
 
       describe('errors', () => {