uima-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Marshall Schor <...@schor.com>
Subject Re: svn commit: r1762163 - /uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/SelectFSs.java
Date Mon, 26 Sep 2016 19:37:24 GMT
Hi Richard,

I see with this update that you converted javadoc style comments to // style.

Was this to get these out of the javadocs? 

For that purpose, it might look a bit better to use the

/* (single *) ... */ style?

Anyway, I'm in complete agreement that the Javadocs for these are missing and
need to be written :-).  I had these other comments as an internal placeholder
while the APIs got worked out, because once the javadocs go in, the file expands
to the point where it's hard to see things IMHO :-).

-Marshall


On 9/25/2016 4:18 AM, rec@apache.org wrote:
> Author: rec
> Date: Sun Sep 25 08:18:09 2016
> New Revision: 1762163
>
> URL: http://svn.apache.org/viewvc?rev=1762163&view=rev
> Log:
> [UIMA-5115] uv3 select() api for iterators and streams over CAS contents
> - Chain generic types after selecting a type or index
> - Comments are not JavaDoc - changing them into line comments instead of JavaDoc comments
>
>
> Modified:
>     uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/SelectFSs.java
>
> Modified: uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/SelectFSs.java
> URL: http://svn.apache.org/viewvc/uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/SelectFSs.java?rev=1762163&r1=1762162&r2=1762163&view=diff
> ==============================================================================
> --- uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/SelectFSs.java
(original)
> +++ uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/SelectFSs.java
Sun Sep 25 08:18:09 2016
> @@ -35,42 +35,37 @@ import org.apache.uima.jcas.tcas.Annotat
>   */
>  public interface SelectFSs<T extends FeatureStructure> {
>    
> -  /**
> -   * If not specified, defaults to all FSs (unordered) unless AnnotationIndex implied
> -   */
> -  SelectFSs<T> index(String indexName);  
> -  SelectFSs<T> index(FSIndex<T> index);
> -
> -  /**
> -   * if not specified defaults to the index's uppermost type.  
> -   */
> -  SelectFSs<T> type(Type uimaType);
> -  SelectFSs<T> type(String fullyQualifiedTypeName);
> -  SelectFSs<T> type(int jcasClass_dot_type);
> -  SelectFSs<T> type(Class<? extends TOP> jcasClass_dot_class);
> +  // If not specified, defaults to all FSs (unordered) unless AnnotationIndex implied
> +    // Methods take their generic type from the variable to which they are assigned
except for
> +    // index(class) which takes it from its argument.
> +  <N extends TOP> SelectFSs<N> index(String indexName);  
> +  <N extends TOP> SelectFSs<N> index(FSIndex<N> index);
> +
> +  // If not specified defaults to the index's uppermost type.
> +  // Methods take their generic type from the variable to which they are assigned except
for
> +  // type(class) which takes it from its argument.
> +  <N extends TOP> SelectFSs<N> type(Type uimaType);
> +  <N extends TOP> SelectFSs<N> type(String fullyQualifiedTypeName);
> +  <N extends TOP> SelectFSs<N> type(int jcasClass_dot_type);
> +  <N extends TOP> SelectFSs<N> type(Class<N> jcasClass_dot_class);
>      
>  //  SelectFSs<T> shift(int amount); // incorporated into startAt 
>    
> -  /*********************************
> -   * boolean operations
> -   *********************************/
> +  // ---------------------------------
> +  // boolean operations
> +  // ---------------------------------
>  
>    SelectFSs<T> matchType();      // exact type match (no subtypes)
>    SelectFSs<T> matchType(boolean matchType); // exact type match (no subtypes)
>    
> -  /**
> -   * only for AnnotationIndex
> -   */
> +  // only for AnnotationIndex
>    SelectFSs<T> typePriority();
>    SelectFSs<T> typePriority(boolean typePriority);
>  
>    SelectFSs<T> positionUsesType();           // ignored if not ordered index
>    SelectFSs<T> positionUsesType(boolean positionUsesType); // ignored if not ordered
index
>    
> -  /**
> -   * Filters while iterating over Annotations
> -   **/
> -  
> +  // Filters while iterating over Annotations
>    SelectFSs<T> nonOverlapping();  // AI known as unambiguous
>    SelectFSs<T> nonOverlapping(boolean nonOverlapping); // AI
>    
> @@ -80,10 +75,7 @@ public interface SelectFSs<T extends Fea
>    SelectFSs<T> skipEquals();                 
>    SelectFSs<T> skipEquals(boolean skipEquals);
>    
> -  /**
> -   * Miscellaneous
> -   **/
> -  
> +  // Miscellaneous
>    SelectFSs<T> allViews();
>    SelectFSs<T> allViews(boolean allViews);
>    
> @@ -99,40 +91,40 @@ public interface SelectFSs<T extends Fea
>  //  SelectFSs<T> noSubtypes();
>  //  SelectFSs<T> noSubtypes(boolean noSubtypes);
>  
> -  /*********************************
> -   * bounding limits specified
> -   * as part of subselection style
> -   *********************************/
> -  
> -  /*********************************
> -   * starting position specification
> -   * 
> -   * Variations, controlled by: 
> -   *   * typePriority
> -   *   * positionUsesType
> -   *   
> -   * The positional specs imply starting at the 
> -   *   - left-most (if multiple) FS at that position, or
> -   *   - if no FS at the position, the next higher FS
> -   *   - if !typePriority, equal test is only begin/end 
> -   *     -- types ignored or not depending on positionUsesType 
> -   *    
> -   * shifts, if any, occur afterwards
> -   *   - can be positive or negative
> -   *********************************/
> +  // ---------------------------------
> +  // bounding limits specified
> +  // as part of subselection style
> +  // ---------------------------------
> +  
> +  // ---------------------------------
> +  // starting position specification
> +  // 
> +  // Variations, controlled by: 
> +  //   * typePriority
> +  //   * positionUsesType
> +  //   
> +  // The positional specs imply starting at the 
> +  //   - left-most (if multiple) FS at that position, or
> +  //   - if no FS at the position, the next higher FS
> +  //   - if !typePriority, equal test is only begin/end 
> +  //     -- types ignored or not depending on positionUsesType 
> +  //    
> +  // shifts, if any, occur afterwards
> +  //   - can be positive or negative
> +  // ---------------------------------
>    SelectFSs<T> startAt(TOP fs);  // Ordered
>    SelectFSs<T> startAt(int begin, int end);   // AI
>    
>    SelectFSs<T> startAt(TOP fs, int shift);        // Ordered
>    SelectFSs<T> startAt(int begin, int end, int shift);   // AI
>      
> -  /*********************************
> -   * subselection based on bounds
> -   *   - uses 
> -   *     -- typePriority, 
> -   *     -- positionUsesType, 
> -   *     -- skipEquals
> -   *********************************/
> +  // ---------------------------------
> +  // subselection based on bounds
> +  //   - uses 
> +  //     -- typePriority, 
> +  //     -- positionUsesType, 
> +  //     -- skipEquals
> +  // ---------------------------------
>    SelectFSs<T> at(Annotation fs);  // AI
>    SelectFSs<T> at(int begin, int end);  // AI
>    
> @@ -144,10 +136,10 @@ public interface SelectFSs<T extends Fea
>    
>    SelectFSs<T> between(Annotation fs1, Annotation fs2);  // AI implies a coveredBy
style
>    
> -  /*********************************
> -   * terminal operations
> -   * returning other than SelectFSs
> -   *********************************/
> +  // ---------------------------------
> +  // terminal operations
> +  // returning other than SelectFSs
> +  // ---------------------------------
>    FSIterator<T> fsIterator();
>    Iterator<T> iterator();
>    List<T> asList();
> @@ -155,20 +147,20 @@ public interface SelectFSs<T extends Fea
>    T get();
>    T single();
>    
> -  /********************************************
> -   * The methods below are alternatives 
> -   * to the methods above, that combine
> -   * frequently used patterns into more
> -   * concise forms using positional arguments
> -   ********************************************/
> -  
> -  /**
> -   * Semantics: the arg is used to position.
> -   * The position is 
> -   *   - if the arg is a match, then the next/previous one not matching (skip over matches)
> -   *     -- uses typePriority, positionUsesType, and skipEqual for match cas
> -   *   - if the arg is not a match, the first position > or < arg 
> -   */
> +  // ---------------------------------
> +  // The methods below are alternatives 
> +  // to the methods above, that combine
> +  // frequently used patterns into more
> +  // concise forms using positional arguments
> +  // ---------------------------------
> +  
> +  // ---------------------------------
> +  // Semantics: the arg is used to position.
> +  // The position is 
> +  //   - if the arg is a match, then the next/previous one not matching (skip over matches)
> +  //     -- uses typePriority, positionUsesType, and skipEqual for match cas
> +  //   - if the arg is not a match, the first position > or < arg 
> +  // ---------------------------------
>    SelectFSs<T> following(Annotation fs);
>    SelectFSs<T> following(int begin, int end);
>    SelectFSs<T> following(Annotation fs, int offset);
>
>
>


Mime
View raw message