488126: Updated documentation for the new project structure

Change-Id: Ibc6103dbd322c410bf7ca807708623ba085859ab
Task-Url: https://bugs.eclipse.org/bugs/show_bug.cgi?id=488126

doc/org.eclipse.emf.parsley.doc/contents/00-Main.html

@@ -15,7 +15,11 @@ <h1>Emf Parsley Guide</h1>
 		</li>
 		<li><a href="01-Overview.html#Customize">Customize</a>
 		<ol>	<li><a href="01-Overview.html#Customizations_DSL">Customize with the DSL</a>
-			<ol>	<li><a href="01-Overview.html#PluginXml">How the DSL handles the plugin.xml</a>
+			<ol>	<li><a href="01-Overview.html#DslProjectStructure">The structure of an EMF Parsley project</a>
+				</li>
+				<li><a href="01-Overview.html#PluginXml">How the DSL handles the plugin.xml</a>
+				</li>
+				<li><a href="01-Overview.html#InjectorProvider">Obtaining the Injector</a>
 				</li>
 			</ol></li>
 		</ol></li>

doc/org.eclipse.emf.parsley.doc/contents/00-Main_4.html

@@ -15,7 +15,11 @@ <h1>Getting Started</h1>
 	</li>
 	<li><a href="01-Overview.html#Customize">Customize</a>
 	<ol>	<li><a href="01-Overview.html#Customizations_DSL">Customize with the DSL</a>
-		<ol>	<li><a href="01-Overview.html#PluginXml">How the DSL handles the plugin.xml</a>
+		<ol>	<li><a href="01-Overview.html#DslProjectStructure">The structure of an EMF Parsley project</a>
+			</li>
+			<li><a href="01-Overview.html#PluginXml">How the DSL handles the plugin.xml</a>
+			</li>
+			<li><a href="01-Overview.html#InjectorProvider">Obtaining the Injector</a>
 			</li>
 		</ol></li>
 	</ol></li>

doc/org.eclipse.emf.parsley.doc/contents/01-Overview.html

@@ -82,7 +82,7 @@ <h3>Customize with the DSL</h3>
 </div>
 </p>
 <p>
-The DSL allows to customize the most relevant behaviors, currently the following are permitted:
+The DSL allows to customize the most relevant behaviors. Here we list only a few of them:
 </p>
 <p>
 <ul>
@@ -119,6 +119,34 @@ <h3>Customize with the DSL</h3>
 	</li>
 </ul>
 </p>
+<a name="DslProjectStructure"></a>
+<h4>The structure of an EMF Parsley project</h4>
+<p>
+An EMF Parsley project, as created by the wizard, is an Eclipse plug-in project with a few
+additional builders.
+</p>
+<p>
+The <em>emfparsley-gen</em> source folder will contain all the Java files generated by the DSL
+compiler.  The contents of this folder should never be modified manually, since their contents
+will be overwritten by the DSL compiler.
+</p>
+<p>
+The <em>src</em> source folder will contain an <a class="jdoc" href="http://help.eclipse.org/helios/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/ui/plugin/AbstractUIPlugin.html" title="View JavaDoc"><abbr title="org.eclipse.ui.plugin.AbstractUIPlugin" >AbstractUIPlugin</abbr></a> generated
+by the wizard. This is generated only during the creation of the project and it can be safely modified
+if you need to put other mechanisms in the activator.
+</p>
+<p>
+IMPORTANT: it is crucial that the activator has the static method <em>getDefault</em>, so you must not remove
+that method.
+</p>
+<p>
+If you choose one of the templates provided by the wizard, the <em>src</em> folder will also contain
+a Java class for the view, which extends the corresponding view of Parsley.  This can be safely modified
+if you need to add some additional mechanisms or contents to the view.
+</p>
+<p>
+You can then create additional <em>.parsley</em> files in the same project.
+</p>
 <a name="PluginXml"></a>
 <h4>How the DSL handles the plugin.xml</h4>
 <p>
@@ -147,6 +175,53 @@ <h4>How the DSL handles the plugin.xml</h4>
 and use the context menu "Compare With" =&gt; "Each Other".  This way, you will soon detect the
 changes that have to be manually applied.
 </p>
+<a name="InjectorProvider"></a>
+<h4>Obtaining the Injector</h4>
+<p>
+Since we also generate the <em>plugin.xml</em> starting from the DSL file, we already make sure that the
+views will be created via Google Guice injection mechanisms, using a generated
+<em>executable extension factory</em>.
+</p>
+<p>
+If you need to obtain an injector corresponding to a specific DSL file, you can use the
+corresponding generated class <em>injector provider</em>.  This is prefixed with the name of the module
+(first letter capitalized).  For example, given this DSL module
+</p>
+<p>
+<div class="literallayout">
+<div class="incode">
+<p class="code">
+<span class="keyword">module</span>&nbsp;org.eclipse.emf.parsley.examples.firstexample&nbsp;{<br/>
+&nbsp;&nbsp;&nbsp;&nbsp;...<br/>
+}<br/>
+</p>
+</div>
+</div>
+</p>
+<p>
+The Java class for the injector provider will be <em>org.eclipse.emf.parsley.examples.firstexample.FirstexampleInjectorProvider</em>.
+</p>
+<p>
+These injector providers have a static method <em>getInjector()</em> that will return the <em>singleton</em> injector
+corresponding to that module:
+</p>
+<p>
+<div class="literallayout">
+<div class="incode">
+<p class="code">
+Injector&nbsp;injector&nbsp;=&nbsp;FirstexampleInjectorProvider.getInjector();<br/>
+</p>
+</div>
+</div>
+</p>
+<p>
+The returned injector is <em>singleton</em> in the sense that it is the same injector used
+to create instances of the view parts specified as extension points in the <em>plugin.xml</em>.
+</p>
+<p>
+Obtaining the injector this way is useful, for example, when you develop a pure e4 application,
+where you do not define views in the <em>plugin.xml</em>.  See <a href="07-Eclipse4.html#Eclipse4" title="Go to &quot;Eclipse 4.x&quot;">Eclipse 4.x</a>.
+</p>
 <p>
 
 </p>

doc/org.eclipse.emf.parsley.doc/contents/07-Eclipse4.html

@@ -149,6 +149,11 @@ <h2>Using a TreeComposite into an e4 Part</h2>
 </div>
 </p>
 <p>
+The Google Guice Injector (not to be confused with the Eclipse e4 Injector) is retrieved
+using the injector provider class generated by the DSL compiler
+(see also <a href="01-Overview.html#InjectorProvider" title="Go to &quot;Obtaining the Injector&quot;">Obtaining the Injector</a>).
+</p>
+<p>
 If you now run the application you will be able to manage the model:
 </p>
 <p>

doc/org.eclipse.emf.parsley.doc/contents/Migration-Guide.html

@@ -15,7 +15,13 @@ <h2>From 0.6.0 to 0.7.0</h2>
 <p>
 <ul>
 	<li>
-		<em>Structure of projects</em>: the structure of EMF Parsley projects has radically changed.
+		<em>Multiple DSL files in the same project</em>: thanks to the radical change to the structure
+		of EMF Parsley projects, detailed in the following, it is now possible to define several
+		<em>.parsley</em> files in the same project.
+	</li>
+	<li>
+		<em>Structure of projects</em>: the structure of EMF Parsley projects has radically changed
+		(see <a href="01-Overview.html#DslProjectStructure" title="Go to &quot;The structure of an EMF Parsley project&quot;">The structure of an EMF Parsley project</a>).
 		If you have existing projects you need to perform these steps to adjust the compilation errors you will
 		get:
 		<ol>
@@ -80,7 +86,8 @@ <h2>From 0.6.0 to 0.7.0</h2>
 	<li>
 		<em>InjectorProvider</em>: the activator generated by the project wizard does not provide
 		anymore a means to retrieve the injector.  This functionality is now implemented by an <em>InjectorProvider</em>
-		class which is automatically generated for each DSL module.  For example, in the first example,
+		class which is automatically generated for each DSL module (see <a href="01-Overview.html#InjectorProvider" title="Go to &quot;Obtaining the Injector&quot;">Obtaining the Injector</a>).
+		For example, in the first example,
 		<a href="02-FirstExample.html#FirstExample" title="Go to &quot;First Example&quot;">First Example</a>, instead of doing
 		<div class="literallayout">
 		<div class="incode">

doc/org.eclipse.emf.parsley.doc/contents/toc.xml

@@ -6,8 +6,12 @@
 			</topic>
 			<topic href="contents/01-Overview.html#Customize" label="Customize" >
 				<topic href="contents/01-Overview.html#Customizations_DSL" label="Customize with the DSL" >
+					<topic href="contents/01-Overview.html#DslProjectStructure" label="The structure of an EMF Parsley project" >
+					</topic>
 					<topic href="contents/01-Overview.html#PluginXml" label="How the DSL handles the plugin.xml" >
 					</topic>
+					<topic href="contents/01-Overview.html#InjectorProvider" label="Obtaining the Injector" >
+					</topic>
 				</topic>
 			</topic>
 		</topic>

doc/org.eclipse.emf.parsley.doc/xdoc/documentation/01-Overview.xdoc

@@ -42,7 +42,7 @@ to discover all features.
 
 img[images/01-dsl-content-assistant.png][][ ][] 
 
-The DSL allows to customize the most relevant behaviors, currently the following are permitted:
+The DSL allows to customize the most relevant behaviors. Here we list only a few of them:
 
 ul[
 	item[e[parts] lets you define your View Parts: this will correspond to the standard Eclipse extension
@@ -69,6 +69,28 @@ ul[
 	Different implementations can be defined forfor e[dialogs] and e[forms]]
 ]
 
+section3:DslProjectStructure[The structure of an EMF Parsley project]
+
+An EMF Parsley project, as created by the wizard, is an Eclipse plug-in project with a few
+additional builders.
+
+The e[emfparsley-gen] source folder will contain all the Java files generated by the DSL
+compiler.  The contents of this folder should never be modified manually, since their contents
+will be overwritten by the DSL compiler.
+
+The e[src] source folder will contain an codeRef[org.eclipse.ui.plugin.AbstractUIPlugin] generated
+by the wizard. This is generated only during the creation of the project and it can be safely modified
+if you need to put other mechanisms in the activator.
+
+IMPORTANT: it is crucial that the activator has the static method e[getDefault], so you must not remove
+that method.
+
+If you choose one of the templates provided by the wizard, the e[src] folder will also contain
+a Java class for the view, which extends the corresponding view of Parsley.  This can be safely modified
+if you need to add some additional mechanisms or contents to the view.
+
+You can then create additional e[.parsley] files in the same project.
+
 section3:PluginXml[How the DSL handles the plugin.xml]
 
 If you specify any e[part] in the DSL file, then
@@ -94,6 +116,37 @@ the e[plugin.xml] accordingly.  The easiest way is to select to the files,
 and use the context menu "Compare With" => "Each Other".  This way, you will soon detect the
 changes that have to be manually applied.
 
+section3:InjectorProvider[Obtaining the Injector]
+
+Since we also generate the e[plugin.xml] starting from the DSL file, we already make sure that the
+views will be created via Google Guice injection mechanisms, using a generated
+e[executable extension factory].
+
+If you need to obtain an injector corresponding to a specific DSL file, you can use the
+corresponding generated class e[injector provider].  This is prefixed with the name of the module
+(first letter capitalized).  For example, given this DSL module
+
+code[EmfParsley][
+module org.eclipse.emf.parsley.examples.firstexample {
+	...
+}
+]
+
+The Java class for the injector provider will be e[org.eclipse.emf.parsley.examples.firstexample.FirstexampleInjectorProvider].
+
+These injector providers have a static method e[getInjector()] that will return the e[singleton] injector
+corresponding to that module:
+
+code[Java][
+Injector injector = FirstexampleInjectorProvider.getInjector();
+]
+
+The returned injector is e[singleton] in the sense that it is the same injector used
+to create instances of the view parts specified as extension points in the e[plugin.xml].
+
+Obtaining the injector this way is useful, for example, when you develop a pure e4 application,
+where you do not define views in the e[plugin.xml].  See ref:Eclipse4[Eclipse 4.x].
+
 %%section2:Customitations_TheHardWay[The Hard way]
 %%
 %%If you need a deeper degree of customizations, you can use the injection mechanism based on Google Guice.

doc/org.eclipse.emf.parsley.doc/xdoc/documentation/07-Eclipse4.xdoc

@@ -104,6 +104,10 @@ public void postConstruct(Composite parent) throws Exception {
 }
 ]
 
+The Google Guice Injector (not to be confused with the Eclipse e4 Injector) is retrieved
+using the injector provider class generated by the DSL compiler
+(see also ref:InjectorProvider[Obtaining the Injector]).
+
 If you now run the application you will be able to manage the model:
 
 img[images/07-eclipse4-part.png][][ ][]

doc/org.eclipse.emf.parsley.doc/xdoc/documentation/Migration-Guide.xdoc

@@ -4,7 +4,12 @@ section:SixSeven[From 0.6.0 to 0.7.0]
 
 ul[
 
-item[e[Structure of projects]: the structure of EMF Parsley projects has radically changed.
+item[e[Multiple DSL files in the same project]: thanks to the radical change to the structure
+of EMF Parsley projects, detailed in the following, it is now possible to define several
+e[.parsley] files in the same project.]
+
+item[e[Structure of projects]: the structure of EMF Parsley projects has radically changed
+(see ref:DslProjectStructure[The structure of an EMF Parsley project]).
 If you have existing projects you need to perform these steps to adjust the compilation errors you will
 get:
 
@@ -46,7 +51,9 @@ of your project, and perform a clean of the project.
 
 item[e[InjectorProvider]: the activator generated by the project wizard does not provide
 anymore a means to retrieve the injector.  This functionality is now implemented by an e[InjectorProvider]
-class which is automatically generated for each DSL module.  For example, in the first example,
+class which is automatically generated for each DSL module (see ref:InjectorProvider[Obtaining the Injector]).
+
+For example, in the first example,
 ref:FirstExample[First Example], instead of doing
 
 code[Java][

releng/org.eclipse.emf.parsley.parent/pom.xml

@@ -228,14 +228,6 @@
 				<module>../../examples/org.eclipse.emf.parsley.examples.library.editor</module>
 				<module>../../examples/org.eclipse.emf.parsley.examples.views</module>
 				<module>../../examples/org.eclipse.emf.parsley.examples.editors</module>
-
-				<module>../../examples/org.eclipse.emf.parsley.examples.mail.model</module>
-				<module>../../examples/org.eclipse.emf.parsley.examples.mail.accountsview</module>
-				<module>../../examples/org.eclipse.emf.parsley.examples.mail.mailsview</module>
-				<module>../../examples/org.eclipse.emf.parsley.examples.mail.messageview</module>
-				<module>../../examples/org.eclipse.emf.parsley.examples.mail.rcp</module>
-				<module>../../examples/org.eclipse.emf.parsley.examples.mail.product.feature</module>
-				<module>../../tests/org.eclipse.emf.parsley.tests.swtbot.examples</module>
 
 				<module>../../tests/org.eclipse.emf.parsley.tests.swtbot.feature</module>
 				<module>../../tests/org.eclipse.emf.parsley.tests.swtbot</module>
@@ -244,10 +236,18 @@
 				<module>../../examples/org.eclipse.emf.parsley.examples.cdo.server</module>
 				<module>../../examples/org.eclipse.emf.parsley.examples.cdo.model</module>
 				<module>../../examples/org.eclipse.emf.parsley.examples.cdo.treeform</module>
-		
+
 				<module>../../tests/org.eclipse.emf.parsley.tests.swtbot.cdo.feature</module>
 				<module>../../tests/org.eclipse.emf.parsley.tests.swtbot.cdo</module>
-
+
+				<module>../../examples/org.eclipse.emf.parsley.examples.mail.model</module>
+				<module>../../examples/org.eclipse.emf.parsley.examples.mail.accountsview</module>
+				<module>../../examples/org.eclipse.emf.parsley.examples.mail.mailsview</module>
+				<module>../../examples/org.eclipse.emf.parsley.examples.mail.messageview</module>
+				<module>../../examples/org.eclipse.emf.parsley.examples.mail.rcp</module>
+				<module>../../examples/org.eclipse.emf.parsley.examples.mail.product.feature</module>
+				<module>../../tests/org.eclipse.emf.parsley.tests.swtbot.examples</module>
+
 				<module>../../releng/org.eclipse.emf.parsley.repository</module>
 			</modules>
 		</profile>