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, r...@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); > > >
