Added more usage guidelines

Author: shai-almog

README.md

@@ -7,7 +7,7 @@ it doesn't work with the popups in common IDE's and isn't as searchable.
 Gist makes source embedding trivial since you can embed a single sample in multiple methods/classes and manage the sample
 itself in a centeral location. 
 
-With this tool you can get JavaDoc that looks like this: https://www.codenameone.com/javadoc/com/codename1/location/LocationManager.html
+Which makes it look like this: https://www.codenameone.com/javadoc/com/codename1/location/LocationManager.html
 
 With JavaScript enabled you see this:
 
@@ -17,9 +17,22 @@ Without JavaScript (or in IDE/search engine) you will see this:
 
 ![Without JavaScript](without-javascript-gist.png)
 
+Those screenshots were generated by this javadoc, notice that all the source comes from [this gist](https://gist.github.com/codenameone/b0fa5280bde905a8f0cd):
 
-The JavaDoc source embed tool allows you to use gist embeds directly in your javadoc without any change! When you 
-generate JavaDoc it queries github for the gist contents and embeds it as a `<noscript>` 
+```java
+/**
+ * <p>The LocationManager is the main entry to retrieveLocation or to bind  a LocationListener, important: in 
+ * order to use location on iOS you will need to define the build argument ios.locationUsageDescription.
+ * This build argument should be used to describe to Apple &amp; the users why you need to use the location 
+ * functionality.</p>
+ * 
+ * <p>Usage:</p>
+ * <script src="https://gist.github.com/codenameone/b0fa5280bde905a8f0cd.js"></script>
+ */
+public abstract class LocationManager {
+ ```
+
+When you generate JavaDoc it queries github for the gist contents and embeds it as a `<noscript>` 
 alternative right into the code. This means IDE code completion will "just work" as it will have a sensible fallback.
 
 Just pass the source directory and an output directory to the jar file and then generate the javadoc based on the output
@@ -35,6 +48,8 @@ java -jar JavaDocSourceEmbed-1.0-SNAPSHOT.jar pathToSrcDir/src build/tempJavaSou
 javadoc -protected -d dist/javadoc -windowtitle "Codename One API" build/tempJavaSources
 ```
 
+IMPORTANT: notice that we use a temporary directory to generate the source and don't generate to the original directory. The reason for that is simple. If you change the gist or add additional gists in the future youd want them to be updated.
+
 Or using ant you can do something like:
 
 ```xml