From da30aaede9639e0d88717b094b02af4c904e4c84 Mon Sep 17 00:00:00 2001
From: Martin Aeschlimann <martinae@microsoft.com>
Date: Mon, 27 Jun 2016 09:52:49 +0200
Subject: [PATCH] Update readme.md

---
 README.md       | 36 +++++++++++++++++++++++++++++++++++-
 src/monaco.d.ts |  4 ++--
 2 files changed, 37 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 66a16e0f..dac5ff7a 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,45 @@
 # Monaco JSON
 
-JSON language plugin for the Monaco Editor.
+JSON language plugin for the Monaco Editor. It provides the following features when editing JSON files:
+* Code completion, based on JSON schemas or by looking at similar objects in the same file
+* Hovers, based on JSON schemas
+* Validation: Syntax errors and schema validation
+* Formatting
+* Document Symbols
+* Syntax highlighting
 
+Schemas can be provided by configuration. See ([here](https://github.com/Microsoft/monaco-json/blob/master/src/monaco.d.ts) for the API that the
+JSON plugin offers to configure the JSON language support.
+
+Internally the JSON plugin uses the [vscode-json-languageservice](https://github.com/Microsoft/vscode-json-languageservice)
+node module, providing the implementation of the functionally listed above. The same module is also used
+in [VSCode](https://github.com/Microsoft/vscode) to power the JSON editing experience.
 
 ## Installing
 
 This npm module is bundled and distributed in the [monaco-editor](https://www.npmjs.com/package/monaco-editor) npm module.
 
+## Dev: cheat sheet
+
+* initial setup with `npm install .`
+* compile with `npm run watch`
+* bundle with `npm run prepublish`
+
+## Dev: Running monaco-json from source
+
+* clone https://github.com/Microsoft/monaco-json in `$/src/monaco-json`
+* run `$/src/monaco-json> npm run watch`
+* clone https://github.com/Microsoft/monaco-editor in `$/src/monaco-editor`
+* run `$/src/monaco-editor> npm run simpleserver`
+* open http://localhost:8080/monaco-editor/test/?monaco-json=dev
+
+### [Optional] Running monaco-editor-core from source
+
+* this is only needed when you want to make changes also in `monaco-editor-core`.
+* clone https://github.com/Microsoft/vscode in `$/src/vscode/`
+* run `$/src/vscode> gulp watch`
+* open http://localhost:8080/monaco-editor/test/?monaco-json=dev&editor=dev
+
+
 ## License
 [MIT](https://github.com/Microsoft/monaco-json/blob/master/LICENSE.md)
diff --git a/src/monaco.d.ts b/src/monaco.d.ts
index 1d3b1c99..417f73bc 100644
--- a/src/monaco.d.ts
+++ b/src/monaco.d.ts
@@ -6,11 +6,11 @@
 declare module monaco.languages.json {
     export interface DiagnosticsOptions {
         /**
-         * If set, the validator will return syntax errors.
+         * If set, the validator will be enabled and perform syntax validation as well as schema based validation.
          */
         validate?: boolean;
         /**
-         * If set, comments are toleranted. If not set, a syntax error is emmited for comments.
+         * If set, comments are tolerated. If set to false, syntax errors will be emmited for comments.
          */
         allowComments?: boolean;
         /**