make main.js executable and flesh out README

Summary:
Add some minor docs on how to use tsickle as a user.

It sounds like we might fold this into the ng tsc_wrapped so I
think this is all I'll do on this.

Reviewers: alexeagle, rkirov

Reviewed By: alexeagle, rkirov

Subscribers: alexeagle, typescript-eng

Differential Revision: https://reviews.angular.io/D141

Author: evmar

README.md

@@ -1,17 +1,44 @@
 # Tsickle - TypeScript to Closure Annotator [![Build Status](https://travis-ci.org/angular/tsickle.svg?branch=master)](https://travis-ci.org/angular/tsickle)
 
-Tsickle processes TypeScript and adds [Closure Compiler](https://github.com/google/closure-compiler/)
--compatible JSDoc annotations. This allows using TypeScript to transpile your sources, and then
-Closure Compiler to bundle and optimize them, while taking advantage of type information in Closure
-Compiler.
+Tsickle processes TypeScript and adds [Closure Compiler]-compatible JSDoc
+annotations. This allows using TypeScript to transpile your sources, and then
+Closure Compiler to bundle and optimize them, while taking advantage of type
+information in Closure Compiler.
+
+[Closure Compiler]: https://github.com/google/closure-compiler/
 
 ## Installation
 
-- execute `npm i` to install the dependencies,
+- Execute `npm i` to install the dependencies.
+
+## Usage
+
+### Project Setup
+
+Tsickle works by wrapping `tsc`.  To use it, you must set up your project such
+that it builds correctly when you run `tsc` from the command line, by
+configuring the settings in `tsconfig.json`.
+
+If you have complicated tsc command lines and flags in a build file (like a
+gulpfile etc.) Tsickle won't know about it.  Another reason it's nice to put
+everything in `tsconfig.json` is so your editor inherits all these settings as
+well.
 
-## Gulp tasks
+### Invocation
 
-- `gulp watch` executes the unit tests in watch mode (use `gulp test.unit` for a single run),
+Run `tsickle --help` for the full syntax, but basically you specify the minified
+output bundle path and the input TypeScript project.
+
+## Development
+
+### Gulp tasks
+
+- `gulp watch` executes the unit tests in watch mode (use `gulp test.unit` for a
+  single run),
 - `gulp test.e2e` executes the e2e tests,
-- `gulp test.check-format` checks the source code formatting using `clang-format`,
+- `gulp test.check-format` checks the source code formatting using
+  `clang-format`,
 - `gulp test` runs unit tests, e2e tests and checks the source code formatting.
+
+Export the environment variable `UPDATE_GOLDENS=1` to have the test suite
+rewrite the golden files when you run it.

package.json

@@ -18,7 +18,7 @@
   },
   "devDependencies": {
     "chai": "^2.1.1",
-    "clang-format": "1.0.37",
+    "clang-format": "^1.0.41",
     "glob": "^7.0.0",
     "google-closure-compiler": "^20160315.2.0",
     "gulp": "^3.8.11",

src/main.ts

@@ -1,3 +1,5 @@
+#!/usr/bin/env node
+
 import * as closure from 'google-closure-compiler';
 import * as fs from 'fs';
 import * as minimist from 'minimist';

src/tsickle.ts

@@ -1,6 +1,8 @@
 import * as ts from 'typescript';
-import {TypeTranslator} from './type-translator';
+
 import {Rewriter} from './rewriter';
+import {TypeTranslator} from './type-translator';
+
 export {convertDecorators} from './decorator-annotator';
 
 export interface Options {

test/decorator-annotator_test.ts

@@ -1,6 +1,8 @@
-import {convertDecorators} from '../src/decorator-annotator';
 import {expect} from 'chai';
+
+import {convertDecorators} from '../src/decorator-annotator';
 import * as tsickle from '../src/tsickle';
+
 import * as test_support from './test_support';
 
 const testCaseFileName = 'testcase.ts';

test/test_support.ts

@@ -1,10 +1,11 @@
 import * as fs from 'fs';
-import * as ts from 'typescript';
 import * as glob from 'glob';
 import * as path from 'path';
+import * as ts from 'typescript';
 
 import * as tsickle from '../src/tsickle';
 
+
 /** The TypeScript compiler options used by the test suite. */
 const compilerOptions: ts.CompilerOptions = {
   target: ts.ScriptTarget.ES6,