[471900] Update documentation

Added a precision regarding interpreters compatible with F3 navigation
Added a paragraph about the possibility to open a Java service class by
double clicking on its definition in the VSM.

Bug: 471900
Change-Id: I8ee64cfd17341caf601c41666deb3bbb6137cb3b
Signed-off-by: Pierre Guilet <pierre.guilet@obeo.fr>

3 files changed, 23 insertions, 5 deletions

diff --git a/plugins/org.eclipse.sirius.doc/doc/specifier/general/Writing_Queries.html b/plugins/org.eclipse.sirius.doc/doc/specifier/general/Writing_Queries.html
index 1578f6deac..1e9501a6db 100644
--- a/plugins/org.eclipse.sirius.doc/doc/specifier/general/Writing_Queries.html
+++ b/plugins/org.eclipse.sirius.doc/doc/specifier/general/Writing_Queries.html
@@ -37,7 +37,7 @@
 						<a href="#service_methods">Writing Java Services</a>
 					</li>
 					<li>
-						<a href="#service_navigation">Accessing Java service implementations from interpreted expression</a>
+						<a href="#service_navigation">Accessing Java service implementations from interpreted expression or Java extension</a>
 					</li>
 					<li>
 						<a href="#standard_services">Standard Services</a>
@@ -336,7 +336,11 @@
     }
 }
 </code></pre>
-		<p>Once a service has been defined and its class is registered in your VSM, you can invoke it in the expressions of languages which support it  like this: <code>[aFamily.getFamiliesContainingParents()/]</code>. (using Acceleo syntax) The invocation looks as if the service was a normal feature of the 
+		<p>After defining a service, you have to register it in your VSM with a Java extension:</p>
+		<p>
+			<img border="0" src="images/serviceVsmRegistration.png"/>
+		</p>
+		<p>Then you can invoke it in the expressions of languages which support it  like this: <code>[aFamily.getFamiliesContainingParents()/]</code>. (using Acceleo syntax) The invocation looks as if the service was a normal feature of the 
 			<code>Family</code> type. When the service is invoked, the model element on which it is invoked is used as the first argument to the Java method. If arguments are passed in the expression, they are mapped to the second, third, etc. parameters of the Java method, assuming the types are compatible. The result of evaluating a service invocation is the result of the Java method.
 		</p>
 		<p>
@@ -354,7 +358,7 @@
 				<code>void</code>. You can return any value instead, for example target argument (the service method&#8217;s first parameter). 
 			</li>
 		</ul>
-		<h2 id="service_navigation">Accessing Java service implementations from interpreted expression</h2>
+		<h2 id="service_navigation">Accessing Java service implementations from interpreted expression or Java extension</h2>
 		<p>If you want to see the service implementation(s) used in an interpreted expression in the Java editor, you just have to put your cursor on the service and press the 
 			<strong>F3</strong> keyboard key. Three scenarios can occur after hitting F3:
 		</p>
@@ -366,6 +370,13 @@
 		<p>
 			<img border="0" src="images/serviceNavigation.png"/>
 		</p>
+		<p>
+			<em>Warning:</em> This functionnality works only with 
+			<code>service:</code> and 
+			<code>aql:</code> interpreters, not with the Acceleo 3/MTL 
+			<code>[/]</code> interpreter.
+		</p>
+		<p>You also can open the service class specified in a Java extension by a double click on it in the VSM. It will open a Java editor if the qualified name corresponds to an existing implementation. </p>
 		<h2 id="standard_services">Standard Services</h2>
 		<p>Sirius provides some standard services that can be used from any VSM simply by adding the appropriate reference (as a 
 			<em>Java Extension</em>) to the implementation class&#8217;s fully qualified name. When using such a service class, make sure your 
diff --git a/plugins/org.eclipse.sirius.doc/doc/specifier/general/Writing_Queries.textile b/plugins/org.eclipse.sirius.doc/doc/specifier/general/Writing_Queries.textile
index 560cb7b301..0ab8e45e9b 100644
--- a/plugins/org.eclipse.sirius.doc/doc/specifier/general/Writing_Queries.textile
+++ b/plugins/org.eclipse.sirius.doc/doc/specifier/general/Writing_Queries.textile
@@ -145,7 +145,12 @@ public class EObjectServices {
     }
 }
 
-Once a service has been defined and its class is registered in your VSM, you can invoke it in the expressions of languages which support it  like this: <code>[aFamily.getFamiliesContainingParents()/]</code>. (using Acceleo syntax) The invocation looks as if the service was a normal feature of the @Family@ type. When the service is invoked, the model element on which it is invoked is used as the first argument to the Java method. If arguments are passed in the expression, they are mapped to the second, third, etc. parameters of the Java method, assuming the types are compatible. The result of evaluating a service invocation is the result of the Java method.
+After defining a service, you have to register it in your VSM with a Java extension:
+
+!images/serviceVsmRegistration.png!
+
+
+Then you can invoke it in the expressions of languages which support it  like this: <code>[aFamily.getFamiliesContainingParents()/]</code>. (using Acceleo syntax) The invocation looks as if the service was a normal feature of the @Family@ type. When the service is invoked, the model element on which it is invoked is used as the first argument to the Java method. If arguments are passed in the expression, they are mapped to the second, third, etc. parameters of the Java method, assuming the types are compatible. The result of evaluating a service invocation is the result of the Java method.
 
 
 
@@ -155,7 +160,7 @@ _Warning:_ There are currently some limitations on the use of Java services from
 * primitive types can not be used as arguments or return types for service methods invoked from Acceleo 3 expressions. The workaround is to use the corresponding wrapper type (e.g. @Integer@ instead of @int@).
 * service methods invoked from Acceleo 3 expressions can not return @void@. You can return any value instead, for example target argument (the service method's first parameter). 
 
-h2(#service_navigation). Accessing Java service implementations from interpreted expression
+h2(#service_navigation). Accessing Java service implementations from interpreted expression or Java extension
 
 If you want to see the service implementation(s) used in an interpreted expression in the Java editor, you just have to put your cursor on the service and press the *F3* keyboard key. Three scenarios can occur after hitting F3:
 * Nothing happens if your service does not exist in any services class defined in the VSM or if the expression is not complete (missing parenthesis and parameters).
@@ -163,7 +168,9 @@ If you want to see the service implementation(s) used in an interpreted expressi
 * If many implementations match your service call, a wizard is opened and allows you to choose the Java class containing the service implementation you wish to see:
 !images/serviceNavigation.png!
 
+_Warning:_ This functionnality works only with @service:@ and @aql:@ interpreters, not with the Acceleo 3/MTL @[/]@ interpreter.
 
+You also can open the service class specified in a Java extension by a double click on it in the VSM. It will open a Java editor if the qualified name corresponds to an existing implementation. 
 
 h2(#standard_services). Standard Services
 
diff --git a/plugins/org.eclipse.sirius.doc/doc/specifier/general/images/serviceVsmRegistration.png b/plugins/org.eclipse.sirius.doc/doc/specifier/general/images/serviceVsmRegistration.png
new file mode 100644
index 0000000000..50489d1f37
--- /dev/null
+++ b/plugins/org.eclipse.sirius.doc/doc/specifier/general/images/serviceVsmRegistration.png