Add some sensible content to vscode-boot-java readme

vscode-extensions/vscode-boot-java/DEVELOPER-NOTES.md

@@ -0,0 +1,60 @@
+# Developer notes
+
+## Bulding and Running
+
+This project consists of three pieces:
+
+ - a vscode-extension which is a language-server client implemented in TypeScript.
+ - commons-vscode: a local npm module with some utilities implemented in TypeScript.
+ - a language server implemented in Java.
+
+To build all these pieces you normally only need to run:
+
+   npm install
+
+**However, the first time you build** it might fail trying to
+find the `commons-vscode` module on npm central. Once we publish a stable 
+version of that module on npm central that will no longer be a problem. 
+Until that time, you can work around this by doing a one time manual 
+run of the `preinstall` script prior to running `npm install`:
+
+    ./scripts/preinstall.sh
+    npm install
+
+Now you can open the client-app in vscode. From the root of this project.
+
+    code .
+
+To launch the language server in a vscode runtime, press F5.
+
+## Debugging
+
+### Method 1: attach remote debugger to Language Server
+
+To debug the language server, open `lib/Main.ts` and edit to set the
+`DEBUG` option to `true`. When you launch the app next by pressing
+`F5` it will launch with debug options being passed to the server JVM.
+
+You can then connect a 'Remote Java' debugger on port 8000.
+
+### Method 2: Launch a 'standalone' Language Server
+
+To debug the language server, open `lib/Main.ts` and edit to set the
+`CONNECT_TO_LS` option to `true`. When you launch the app next by pressing
+`F5`... When it needs a language server it not launch a process but instead
+try to connect to an already running server on port `5007`. It is up to you
+to ensure a server is running on that port by launching it beforehand 
+with a commandline arguments: `-Dstandalone-startup=true`.
+
+## Packaging as a vscode extension
+
+First make sure the stuff is all built locally:
+
+     ./scripts/preinstall.sh  # only needed if this is the first build.
+     npm install
+
+Then package it:
+
+     npm run vsce-package
+
+This produces a `.vsix` file which you can install directly into vscode.

vscode-extensions/vscode-boot-java/README.md

@@ -2,72 +2,89 @@
 
 VSCode extension and Language Server providing support for working with Spring Boot apps in Java.
 
-## Installation:
-
-Currently this plugin is not distributed via vscode marketplace. You can only install
-it from a .vsix file. You can download it here:
-
-   TODO: add link
-
-To install it:
-
-- open vscode. 
-- press `CTRL-SHIFT-P` and search for VSIX
-- select `Extension: Install from VSIX`
-
-## Usage:
+# Usage:
 
 The extension will automatically activate when you edit files with the following
 name patterns:
 
  - `*.java` => activates support for Java files
 
-# Developer notes
+# Functionality
 
-## Bulding and Running
+## Navigating the source code - Go to symbol in file/workspace
+Easy navigation to Spring-specific elements of your source code.
 
-This project consists of three pieces:
+![Go to Symbol in workspace][screenshot-navigation]
 
- - a vscode-extension which is a language-server client implemented in TypeScript.
- - commons-vscode: a local npm module with some utilities implemented in TypeScript.
- - a language server implemented in Java.
+### Shortcuts
+* Mac: Cmd-Shift-O (symbols in file), Cmd-T (symbols in workspace)
+* Linux/Windows: Ctrl-Shift-O (symbols in file), Ctrl-T (symbols in workspace)
 
-To build all these pieces you normally only need to run:
+### Examples
+* `@/` shows all defined request mappings (mapped path, request method, source location)
+* `@+` shows all defined beans (bean name, bean type, source location)
+* `@>` shows all functions (prototype implementation)
+* `@` shows all Spring annotations in the code
 
-   npm install
+## Quick-access for running apps
+Easy navigation to the provided request mappings of running apps.
 
-**However, the first time you build** it might fail trying to
-find the `commons-vscode` module on npm central. Once we publish a stable 
-version of that module on npm central that will no longer be a problem. 
-Until that time, you can work around this by doing a one time manual 
-run of the `preinstall` script prior to running `npm install`:
+![accessing running apps quickly](screenshot-live-apps-quick-access]
 
-    ./scripts/preinstall.sh
-    npm install
+### Shortcuts
+* Mac: Cmd-Shift-O (symbols in file), Cmd-T (symbols in workspace)
+* Linux/Windows: Ctrl-Shift-O (symbols in file), Ctrl-T (symbols in workspace)
 
-Now you can open the client-app in vscode. From the root of this project.
+### Examples
+* `//` shows all request mappings of all running Spring Boot apps and opens a browser for the selected endpoint
 
-    code .
+## Live application information hovers
+Show information from running Spring Boot apps on your machine in the source code. This allows you to run the Spring Boot app locally on your machine and visualizes information from those running apps in your source code.
 
-To launch the language server in a vscode runtime, press F5.
+### Visualization
+Once the tooling detects a running Spring Boot app on your local machine, it automatically shows hints in the source code where data from the running app can be inspected. Then hovering over that area (with the mouse pointer), the data from the running app shows up.
 
-## Debugging
+If there are multiple instances of the app running on your machine, the live data from all those instances will show up in the hover information.
 
-To debug the language server, open `lib/Main.ts` and edit to set the
-`DEBUG` option to `true`. When you laucnh the app next by pressing
-`F5` it will launch with debug options being passed to the JVM.
+![live data from running apps as hover on source code][screenshot-live-hovers]
 
-You can then connect a 'Remote Java' Eclipse debugger on port 8000.
+### Examples
+* `@Profile`: shows information about the active profiles on the running apps
+* `@Component`, `@Bean`, `@Autowired`: shows detailed information about the beans and their wiring from the live app
+* `@ContidionalOn...`: shows information about the conditions and their evaluation at runtime
 
-## Packaging as a vscode extension
+### Configuration
+You can enable/disable this feature via workspace or user preferences, 
+using the key: `boot-java.boot-hints.on`.
 
-First make sure the stuff is all built locally:
+## Code templates
+Write Spring code with templates, available via regular code completion.
 
-     ./scripts/preinstall.sh  # only needed if this is the first build.
-     npm install
+### Examples
+* `@GetMapping`
+* `@PostMapping`
+* `@PutMapping`
+* `@RequestMapping`
 
-Then package it:
+## Smart code completions
+Additional code completions for Spring-specific annotations
 
-     npm run vsce-package
+![Smart code completion for boot properties][screenshot-code-completion]
 
-This produces a `.vsix` file which you can install directly into vscode.
+### Examples
+* `@Value`: code completion for Spring Boot property keys
+* `@Scope`: code completion for standard scope names
+
+# Releases:
+
+Released versions of this extension can be installed directly from the vscode marketplace.
+
+There are also development snapshots available with the latest fixes and improvements as a `.vsix` file 
+that can be donwloaded from 
+[here](http://dist.springsource.com/snapshot/STS4/nightly-distributions.html). To install it
+open vscode, press `CTRL-SHIFT-P` and search for VSIX, then select `Extension: Install from VSIX`
+
+[screenshot-code-completion]: prefixxx/screenshot-code-completion.png
+[screenshot-live-apps-quick-access]: prefixxx/screenshot-live-apps-quick-access.png
+[screenshot-live-hovers]: prefixxx/screenshot-live-hovers.png
+[screenshot-navigation]: prefixxx/screenshot-navigation.png