[uima-uimaj] branch master updated: [UIMA-6153] improve docs for specifying generic types in select framework, fix some typos too

[sc...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

schor pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/uima-uimaj.git


The following commit(s) were added to refs/heads/master by this push:
     new a9cec9c  [UIMA-6153] improve docs for specifying generic types in select framework, fix some typos too
a9cec9c is described below

commit a9cec9c82819fab09aba43d57a3845ee2dac4f15
Author: Marshall Schor <ms...@schor.com>
AuthorDate: Wed Dec 4 11:34:20 2019 -0500

    [UIMA-6153] improve docs for specifying generic types in select
    framework, fix some typos too
---
 .../src/docbook/uv3.select.xml                     | 63 ++++++++++++++++------
 1 file changed, 46 insertions(+), 17 deletions(-)

diff --git a/uima-docbook-v3-users-guide/src/docbook/uv3.select.xml b/uima-docbook-v3-users-guide/src/docbook/uv3.select.xml
index 7ab05dd..8d5cb47 100644
--- a/uima-docbook-v3-users-guide/src/docbook/uv3.select.xml
+++ b/uima-docbook-v3-users-guide/src/docbook/uv3.select.xml
@@ -220,33 +220,62 @@ under the License.
     
     <para>There is also a static version of the <code>select</code> method which takes a 
     generically typed index as an argument.</para>
+    
+    <para>The best practice is to pass the JCas class representing the type you want, to the select statement.
+      This enables the generic typing mechanism to be set to that type.  In the example below, we use 
+      <code>Token</code> as the type, and <code>fsIterator()</code> just as an example of some terminal form action.
+    </para>
+    
     <informalexample>  <?dbfo keep-together="always"?>  
-    <programlisting>// this works
+    <programlisting>// Best practice, when possible
 // the generic type for Token is passed as an argument to select
 FSIterator&lt;Token&gt; token_it = cas.select(Token.class).fsIterator();
+</programlisting>
+</informalexample>
+
+    <para>A compile-time generic type can be specified after the select, if the class argument form of <code>select</code> 
+        is not used.  In these two examples, the generic type is being specified at compile time, explicitly: </para>  
+    <informalexample>  <?dbfo keep-together="always"?>  
+    <programlisting>// ... myCas.select(myType).&lt;Token&gt;fsIterator() ...  
+// ... myIndexOversomeType.select().&lt;Token&gt;further-operators-of-select-etc
+</programlisting>
+</informalexample>
+
+    <para>Java 8's type inference doesn't take the generic type past the first object in a build chain, so you can
+    use these techniques to overcome that.  In these examples, tkn_idx is a generically typed variable:</para>
+
+    <informalexample>  <?dbfo keep-together="always"?>  
+    <programlisting>FSIndex&lt;Token&gt; tkn_idx = ... ; // generically typed variable
+</programlisting>
+</informalexample>
 
-FSIndex&lt;Token&gt; token_index = ... ; // generically typed
+    <para>We show a straight-forward syntax that doesn't work, followed by 3 alternatives that do work.</para>
+    <informalexample>  <?dbfo keep-together="always"?>  
+    <programlisting>// this next fails because the Token generic type from the 
+// index variable being assigned doesn't get passed to the select().
 
-// this next fails because the
-// Token generic type from the index variable being assigned
-// doesn't get passed to the select().
-FSIterator&lt;Token&gt; token_iterator = token_index.select().fsIterator();
+FSIterator&lt;Token&gt; token_iterator = tkn_idx.select().fsIterator();
+</programlisting>
+</informalexample>
+ 
+   <para>You can overcome this in three ways:</para>
+
+    <informalexample>  <?dbfo keep-together="always"?>  
+    <programlisting>// pass in the type as an argument to select using the JCas cover type.  
 
-// You can overcome this in two ways:
-// pass in the type as an argument to select
-// using the JCas cover type.  
 FSIterator&lt;Token&gt; token_iterator = 
-    token_index.select(Token.class).fsIterator();
+    tkn_idx.select(Token.class).fsIterator();
+
+// Or use the static form of select (avoids repeating the type info)
 
-// You can also use the static form of select
-// to avoid repeating the type information
 FSIterator&lt;Token&gt; token_iterator = 
-    SelectFSs.select(token_index).fsIterator();
+    SelectFSs.select(tkn_idx).fsIterator();
+
+// Or you can also explicitly set the generic type 
+// that select() should use, like this:
 
-// Finally, you can also explicitly set the generic type 
-// that select() should use, like a special kind of type cast, like this:
 FSIterator&lt;Token&gt; token_iterator =
-    token_index.&lt;Token&gt;select().fsIterator();
+    tkn_idx.&lt;Token&gt;select().fsIterator();
 </programlisting>
 </informalexample>
         
@@ -255,7 +284,7 @@ FSIterator&lt;Token&gt; token_iterator =
     
   <para>Any specification of an index may be further restricted to just a subType (including that
   subtype&apos;s subtypes, if any) of that index&apos;s type.
-  For example, an AnnotationIndex may be specialized to just Sentences (and their subtypes):
+  For example, an AnnotationIndex may be specialized to just <code>Token</code>s (and their subtypes):
   <programlisting>FSIterator&lt;Token&gt; token_iterator = 
     annotation_index.select(Token.class).fsIterator();
 </programlisting>