documentation updated for v0.14

Author: elucash

_posts/2013-10-29-when-not-to-use.md _drafts/2013-10-29-when-not-to-use.md_posts/2013-10-29-when-not-to-use.md renamed to _drafts/2013-10-29-when-not-to-use.md

@@ -1,13 +1,10 @@
 ## Docs
 
 - [Get started!](/getstarted.html)
-- [Immutable objects reference](/immutable.html)
-- [JSON marshaling reference](/json.html)
-- MongoDB repositories reference (Coming Soon)
-
-## Posts
-{% for post in site.posts limit: 10 %}
-- [{{ post.title }}]({{ post.url }}){% endfor %}
+- [Immutable objects guide](/immutable.html)
+- [JSON marshaling guide](/json.html)
+- [MongoDB repositories guide](/mongo.html)
+- [Using annotation processor in IDE](/apt.html)
 
 ## Get involved
 

_includes/footer.md

@@ -0,0 +1,3 @@
+## Posts
+{% for post in site.posts limit: 10 %}
+- [{{ post.title }}]({{ post.url }}){% endfor %}

_includes/posts.md

@@ -1,4 +1,5 @@
-Embrace immutablity to tackle complexity and concurrency challenges. To get benefits of immutability in Java we created annotation processor
+Embrace immutability to tackle complexity and concurrency challenges.
+To get benefits of immutability in Java we created the annotation processor
 to easily create simple and consistent value objects. You can think of it as
 [Guava's Immutable Collections](https://code.google.com/p/guava-libraries/wiki/ImmutableCollectionsExplained)
 but for regular objects.

_includes/story0.md

@@ -13,7 +13,7 @@ public abstract class Item {
 ```
 ```java
 // Instantiate generated repository
-ItemRepository items = ItemRepository.create(
+ItemRepository items = new ItemRepository(
     RepositorySetup.forUri("mongodb://localhost/test"));
 
 // Insert async

_includes/storySample2.md

@@ -0,0 +1,60 @@
+---
+title: 'Using annotation processor in IDE'
+layout: page
+---
+
+{% capture v %}0.14{% endcapture %}
+{% capture depUri %}http://search.maven.org/#artifactdetails|org.immutables{% endcapture %}
+--------
+Overview
+--------
+
+As of Java 6 annotation processing became part of standard java compiler.
+Java 7 or higher is required to run _Immutables_ annotation processor.
+_Immutables_ annotation processor runs under any Java build tool that uses `javac` as compiler backend.
+(given annotation processing is not disabled in build tool configuration).
+_Eclipse JDT compiler_ (ECJ) also supports this annotation processor.
+
+Nowadays major IDE supports annotation processing out of the box while importing projects. That
+said there are some quirks that may prevent this functionality to function properly.
+
+Annotation processor that is to be plugged into IDE was built as single jar without external dependencies.
+
+- [org.immutables:generate-tool:{{v}}]({{ depUri }}|generate-tool|{{ v }}|jar)
+
+-------
+Eclipse
+-------
+
+If you are using Maven, then m2e could configure annotation processing for you. However for this to work
+m2e-apt connector should be installed first. Install it from Eclipse marketplace, for example:
+
+<img src="pix/eclipse-marketplace.png">
+
+If it will not work for some reason, you could configure it manually. 
+
+Manual configuration tutorial
+
+* [Using Java 6 processors in Eclipse](http://kerebus.com/2011/02/using-java-6-processors-in-eclipse/)
+
+
+Here's and dialog configuration example to manually configure annotation processor that is already in local
+maven repository. One need to enable annotation processing in the project settings, then configure factory path
+to point to annotation processor jar, in this example, by extending M2_REPO classpath variable (defined by m2e).
+
+<img src="pix/eclipse-annotation-processing.png">
+
+<img src="pix/eclipse-factory-path.png">
+
+
+_This section to be expanded_
+
+-------------
+IntelliJ IDEA
+-------------
+IntelliJ IDEA should configure annotation processing automatically
+
+
+<img src="http://blog.jetbrains.com/idea/files/2009/11/settings.png">
+
+_This section to be expanded_

apt.md

@@ -3,7 +3,7 @@ title: 'Get started!'
 layout: page
 ---
 
-{% capture v %}0.13{% endcapture %}
+{% capture v %}0.14{% endcapture %}
 {% capture depUri %}http://search.maven.org/#artifactdetails|org.immutables{% endcapture %}
 
 ## Prerequisites
@@ -35,7 +35,7 @@ Snippet of maven dependencies:
 
 _Immutables_ annotation processor runs under any Java build tool that uses `javac` as compiler backend
 (given annotation processing is not disabled in build tool configuration).
-_Eclipse JDT compiler_ (ECJ) also supports this annotation processor.
+_Eclipse JDT compiler_ (ECJ) also supports this annotation processor. See [Using annotation processor in IDE](/apt.html).
 
 ## Create immutable object
 

getstarted.md

@@ -246,6 +246,7 @@ ImmutableDoItYourselfContainer.builder()
     .build();
 ```
 
+<a name="optional"></a>
 ### Optional attributes
 
 Attributes declared with return type of `com.google.common.base.Optional<T>`

immutable.md

@@ -8,7 +8,7 @@
     <h1>Immutables<span class="text-muted">.org</span></h1>
     {% capture story0 %}{% include story0.md %}{% endcapture %}{{ story0 | markdownify }}
     <a href="/getstarted.html" class="btn btn-primary btn-lg">Get started!</a>
-    <a href="/immutable.html" class="btn btn-default btn-lg">Read reference...</a>
+    <a href="/immutable.html" class="btn btn-default btn-lg">Read guide...</a>
     <a href="https://twitter.com/ImmutablesOrg" class="pull-right">
       <i class="fa fa-twitter"></i> News and announcements</a>
   </div>
@@ -24,7 +24,7 @@ <h1>Immutables<span class="text-muted">.org</span></h1>
 <section class="jumbotron">
   <div class="container">
     {% capture story1 %}{% include story1.md %}{% endcapture %}{{ story1 | markdownify }}
-    <a href="/json.html" class="btn btn-default btn-lg">Read reference...</a>
+    <a href="/json.html" class="btn btn-default btn-lg">Read guide...</a>
   </div>
 </section>
 
@@ -38,6 +38,7 @@ <h1>Immutables<span class="text-muted">.org</span></h1>
 <section class="jumbotron">
   <div class="container">
     {% capture story2 %}{% include story2.md %}{% endcapture %}{{ story2 | markdownify }}
+    <a href="/mongo.html" class="btn btn-default btn-lg">Read guide...</a>
   </div>
 </section>
 

index.html

@@ -1,9 +1,9 @@
 ---
-title: 'JSON marshaling reference'
+title: 'JSON marshaling guide'
 layout: page
 ---
 
-{% capture v %}0.13{% endcapture %}
+{% capture v %}0.14{% endcapture %}
 {% capture depUri %}http://search.maven.org/#artifactdetails|org.immutables{% endcapture %}
 
 Overview