lucenenet-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From nightowl...@apache.org
Subject [54/58] [abbrv] lucenenet git commit: Grouping: Fixed up documentation comments and license headers
Date Thu, 10 Nov 2016 11:34:05 GMT
Grouping: Fixed up documentation comments and license headers


Project: http://git-wip-us.apache.org/repos/asf/lucenenet/repo
Commit: http://git-wip-us.apache.org/repos/asf/lucenenet/commit/a0a61e24
Tree: http://git-wip-us.apache.org/repos/asf/lucenenet/tree/a0a61e24
Diff: http://git-wip-us.apache.org/repos/asf/lucenenet/diff/a0a61e24

Branch: refs/heads/grouping
Commit: a0a61e243005254e8a92358456fb34a77a678f4d
Parents: d0838cc
Author: Shad Storhaug <shad@shadstorhaug.com>
Authored: Mon Nov 7 05:30:06 2016 +0700
Committer: Shad Storhaug <shad@shadstorhaug.com>
Committed: Tue Nov 8 02:48:33 2016 +0700

----------------------------------------------------------------------
 .../AbstractAllGroupHeadsCollector.cs           |  29 +-
 .../AbstractAllGroupsCollector.cs               |  17 +
 .../AbstractDistinctValuesCollector.cs          |  21 ++
 .../AbstractFirstPassGroupingCollector.cs       |  28 +-
 .../AbstractGroupFacetCollector.cs              | 116 ++++---
 .../AbstractSecondPassGroupingCollector.cs      |  38 +-
 .../BlockGroupingCollector.cs                   | 138 +++++---
 src/Lucene.Net.Grouping/CollectedSearchGroup.cs |  21 +-
 .../Function/FunctionAllGroupHeadsCollector.cs  |  38 +-
 .../Function/FunctionAllGroupsCollector.cs      |  28 +-
 .../Function/FunctionDistinctValuesCollector.cs |  27 +-
 .../FunctionFirstPassGroupingCollector.cs       |  17 +
 .../FunctionSecondPassGroupingCollector.cs      |  17 +
 src/Lucene.Net.Grouping/GroupDocs.cs            |   1 +
 src/Lucene.Net.Grouping/GroupingSearch.cs       | 345 ++++++++++---------
 src/Lucene.Net.Grouping/SearchGroup.cs          |  73 +++-
 .../Term/TermAllGroupHeadsCollector.cs          | 110 ++++--
 .../Term/TermAllGroupsCollector.cs              |  17 +
 .../Term/TermDistinctValuesCollector.cs         |  38 +-
 .../Term/TermFirstPassGroupingCollector.cs      |  17 +
 .../Term/TermGroupFacetCollector.cs             |  52 ++-
 .../Term/TermSecondPassGroupingCollector.cs     |  17 +
 src/Lucene.Net.Grouping/TopGroups.cs            |   2 +-
 .../AbstractGroupingTestCase.cs                 |  17 +
 .../AllGroupHeadsCollectorTest.cs               |  17 +
 .../AllGroupsCollectorTest.cs                   |  17 +
 .../DistinctValuesCollectorTest.cs              |  17 +
 .../GroupFacetCollectorTest.cs                  |  17 +
 .../GroupingSearchTest.cs                       |  17 +
 29 files changed, 934 insertions(+), 375 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/AbstractAllGroupHeadsCollector.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/AbstractAllGroupHeadsCollector.cs b/src/Lucene.Net.Grouping/AbstractAllGroupHeadsCollector.cs
index 279805e..bf3d984 100644
--- a/src/Lucene.Net.Grouping/AbstractAllGroupHeadsCollector.cs
+++ b/src/Lucene.Net.Grouping/AbstractAllGroupHeadsCollector.cs
@@ -3,6 +3,29 @@ using System.Collections.Generic;
 
 namespace Lucene.Net.Search.Grouping
 {
+    /*
+	 * Licensed to the Apache Software Foundation (ASF) under one or more
+	 * contributor license agreements.  See the NOTICE file distributed with
+	 * this work for additional information regarding copyright ownership.
+	 * The ASF licenses this file to You under the Apache License, Version 2.0
+	 * (the "License"); you may not use this file except in compliance with
+	 * the License.  You may obtain a copy of the License at
+	 *
+	 *     http://www.apache.org/licenses/LICENSE-2.0
+	 *
+	 * Unless required by applicable law or agreed to in writing, software
+	 * distributed under the License is distributed on an "AS IS" BASIS,
+	 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	 * See the License for the specific language governing permissions and
+	 * limitations under the License.
+	 */
+
+    /// <summary>
+    /// This collector specializes in collecting the most relevant document (group head) for each group that match the query.
+    /// 
+    /// @lucene.experimental
+    /// </summary>
+    /// <typeparam name="GH"></typeparam>
     public abstract class AbstractAllGroupHeadsCollector<GH> : AbstractAllGroupHeadsCollector
         where GH : AbstractAllGroupHeadsCollector_GroupHead
     {
@@ -127,12 +150,10 @@ namespace Lucene.Net.Search.Grouping
         /// Contains the result of group head retrieval.
         /// To prevent new object creations of this class for every collect.
         /// </summary>
-        public class TemporalResult
+        protected class TemporalResult
         {
-
             public GH groupHead;
             public bool stop;
-
         }
     }
 
@@ -144,7 +165,7 @@ namespace Lucene.Net.Search.Grouping
     /// </para>
     /// </summary>
     /// <remarks>
-    /// LUCENENET: moved this class from of the <see cref="AbstractAllGroupHeadsCollector{TGroupValue}"/>,
+    /// LUCENENET: moved this class from being a nested class of <see cref="AbstractAllGroupHeadsCollector{TGroupValue}"/>,
     /// made it non-generic so the generic closing type doesn't need to be specified in classes that
     /// use <see cref="AbstractAllGroupHeadsCollector_GroupHead"/> as a generic closing type, and renamed 
     /// it from GroupHead to <see cref="AbstractAllGroupHeadsCollector_GroupHead"/> to avoid naming conflicts with nested classes 

http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/AbstractAllGroupsCollector.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/AbstractAllGroupsCollector.cs b/src/Lucene.Net.Grouping/AbstractAllGroupsCollector.cs
index 6f1edb4..a40d0d7 100644
--- a/src/Lucene.Net.Grouping/AbstractAllGroupsCollector.cs
+++ b/src/Lucene.Net.Grouping/AbstractAllGroupsCollector.cs
@@ -3,6 +3,23 @@ using System.Linq;
 
 namespace Lucene.Net.Search.Grouping
 {
+    /*
+	 * Licensed to the Apache Software Foundation (ASF) under one or more
+	 * contributor license agreements.  See the NOTICE file distributed with
+	 * this work for additional information regarding copyright ownership.
+	 * The ASF licenses this file to You under the Apache License, Version 2.0
+	 * (the "License"); you may not use this file except in compliance with
+	 * the License.  You may obtain a copy of the License at
+	 *
+	 *     http://www.apache.org/licenses/LICENSE-2.0
+	 *
+	 * Unless required by applicable law or agreed to in writing, software
+	 * distributed under the License is distributed on an "AS IS" BASIS,
+	 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	 * See the License for the specific language governing permissions and
+	 * limitations under the License.
+	 */
+
     /// <summary>
     /// A collector that collects all groups that match the
     /// query. Only the group value is collected, and the order

http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/AbstractDistinctValuesCollector.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/AbstractDistinctValuesCollector.cs b/src/Lucene.Net.Grouping/AbstractDistinctValuesCollector.cs
index f832b1b..5acc02f 100644
--- a/src/Lucene.Net.Grouping/AbstractDistinctValuesCollector.cs
+++ b/src/Lucene.Net.Grouping/AbstractDistinctValuesCollector.cs
@@ -2,6 +2,23 @@
 
 namespace Lucene.Net.Search.Grouping
 {
+    /*
+	 * Licensed to the Apache Software Foundation (ASF) under one or more
+	 * contributor license agreements.  See the NOTICE file distributed with
+	 * this work for additional information regarding copyright ownership.
+	 * The ASF licenses this file to You under the Apache License, Version 2.0
+	 * (the "License"); you may not use this file except in compliance with
+	 * the License.  You may obtain a copy of the License at
+	 *
+	 *     http://www.apache.org/licenses/LICENSE-2.0
+	 *
+	 * Unless required by applicable law or agreed to in writing, software
+	 * distributed under the License is distributed on an "AS IS" BASIS,
+	 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	 * See the License for the specific language governing permissions and
+	 * limitations under the License.
+	 */
+
     /// <summary>
     /// A second pass grouping collector that keeps track of distinct values for a specified field for the top N group.
     /// 
@@ -80,6 +97,10 @@ namespace Lucene.Net.Search.Grouping
     /// <typeparam name="GC"></typeparam>
     public interface IAbstractDistinctValuesCollector<out GC>
     {
+        /// <summary>
+        /// Returns all unique values for each top N group.
+        /// </summary>
+        /// <returns>all unique values for each top N group</returns>
         IEnumerable<GC> Groups { get; }
     }
 }

http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/AbstractFirstPassGroupingCollector.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/AbstractFirstPassGroupingCollector.cs b/src/Lucene.Net.Grouping/AbstractFirstPassGroupingCollector.cs
index aae0591..62440f1 100644
--- a/src/Lucene.Net.Grouping/AbstractFirstPassGroupingCollector.cs
+++ b/src/Lucene.Net.Grouping/AbstractFirstPassGroupingCollector.cs
@@ -7,6 +7,23 @@ using System.Linq;
 
 namespace Lucene.Net.Search.Grouping
 {
+    /*
+	 * Licensed to the Apache Software Foundation (ASF) under one or more
+	 * contributor license agreements.  See the NOTICE file distributed with
+	 * this work for additional information regarding copyright ownership.
+	 * The ASF licenses this file to You under the Apache License, Version 2.0
+	 * (the "License"); you may not use this file except in compliance with
+	 * the License.  You may obtain a copy of the License at
+	 *
+	 *     http://www.apache.org/licenses/LICENSE-2.0
+	 *
+	 * Unless required by applicable law or agreed to in writing, software
+	 * distributed under the License is distributed on an "AS IS" BASIS,
+	 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	 * See the License for the specific language governing permissions and
+	 * limitations under the License.
+	 */
+
     /// <summary>
     /// FirstPassGroupingCollector is the first of two passes necessary
     /// to collect grouped hits.  This pass gathers the top N sorted
@@ -14,7 +31,7 @@ namespace Lucene.Net.Search.Grouping
     /// is internally collected.
     /// 
     /// <para>
-    /// See {@link org.apache.lucene.search.grouping} for more
+    /// See <a href="https://github.com/apache/lucene-solr/blob/releases/lucene-solr/4.8.0/lucene/grouping/src/java/org/apache/lucene/search/grouping/package.html">org.apache.lucene.search.grouping</a> for more
     /// details including a full code example.
     /// </para>
     /// @lucene.experimental
@@ -39,7 +56,7 @@ namespace Lucene.Net.Search.Grouping
         /// Create the first pass collector.
         /// </summary>
         /// <param name="groupSort">
-        /// The {@link Sort} used to sort the
+        /// The <see cref="Sort"/> used to sort the
         /// groups.  The top sorted document within each group
         /// according to groupSort, determines how that group
         /// sorts against other groups.  This must be non-null,
@@ -404,12 +421,11 @@ namespace Lucene.Net.Search.Grouping
 
     /// <summary>
     /// LUCENENET specific interface used to apply covariance to TGroupValue
+    /// to simulate Java's wildcard generics.
     /// </summary>
     /// <typeparam name="TGroupValue"></typeparam>
     public interface IAbstractFirstPassGroupingCollector<out TGroupValue>
     {
-        // LUCENENET NOTE: We must use IEnumerable rather than ICollection here because we need
-        // this to be covariant
         /// <summary>
         /// Returns top groups, starting from offset.  This may
         /// return null, if no groups were collected, or if the
@@ -418,6 +434,10 @@ namespace Lucene.Net.Search.Grouping
         /// <param name="groupOffset">The offset in the collected groups</param>
         /// <param name="fillFields">Whether to fill to <see cref="SearchGroup.sortValues"/></param>
         /// <returns>top groups, starting from offset</returns>
+        /// <remarks>
+        /// LUCENENET NOTE: We must use <see cref="IEnumerable{TGroupValue}"/> rather than 
+        /// <see cref="ICollection{TGroupValue}"/> here because we need this to be covariant
+        /// </remarks>
         IEnumerable<ISearchGroup<TGroupValue>> GetTopGroups(int groupOffset, bool fillFields);
     }
 }

http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/AbstractGroupFacetCollector.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/AbstractGroupFacetCollector.cs b/src/Lucene.Net.Grouping/AbstractGroupFacetCollector.cs
index 9a079e8..6e3e014 100644
--- a/src/Lucene.Net.Grouping/AbstractGroupFacetCollector.cs
+++ b/src/Lucene.Net.Grouping/AbstractGroupFacetCollector.cs
@@ -4,6 +4,23 @@ using System.Collections.Generic;
 
 namespace Lucene.Net.Search.Grouping
 {
+    /*
+	 * Licensed to the Apache Software Foundation (ASF) under one or more
+	 * contributor license agreements.  See the NOTICE file distributed with
+	 * this work for additional information regarding copyright ownership.
+	 * The ASF licenses this file to You under the Apache License, Version 2.0
+	 * (the "License"); you may not use this file except in compliance with
+	 * the License.  You may obtain a copy of the License at
+	 *
+	 *     http://www.apache.org/licenses/LICENSE-2.0
+	 *
+	 * Unless required by applicable law or agreed to in writing, software
+	 * distributed under the License is distributed on an "AS IS" BASIS,
+	 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	 * See the License for the specific language governing permissions and
+	 * limitations under the License.
+	 */
+
     /// <summary>
     /// Base class for computing grouped facets.
     /// @lucene.experimental
@@ -28,17 +45,18 @@ namespace Lucene.Net.Search.Grouping
             segmentResults = new List<AbstractSegmentResult>();
         }
 
-        /**
-         * Returns grouped facet results that were computed over zero or more segments.
-         * Grouped facet counts are merged from zero or more segment results.
-         *
-         * @param size The total number of facets to include. This is typically offset + limit
-         * @param minCount The minimum count a facet entry should have to be included in the grouped facet result
-         * @param orderByCount Whether to sort the facet entries by facet entry count. If <code>false</code> then the facets
-         *                     are sorted lexicographically in ascending order.
-         * @return grouped facet results
-         * @throws IOException If I/O related errors occur during merging segment grouped facet counts.
-         */
+        /// <summary>
+        /// Returns grouped facet results that were computed over zero or more segments.
+        /// Grouped facet counts are merged from zero or more segment results.
+        /// </summary>
+        /// <param name="size">The total number of facets to include. This is typically offset + limit</param>
+        /// <param name="minCount">The minimum count a facet entry should have to be included in the grouped facet result</param>
+        /// <param name="orderByCount">
+        /// Whether to sort the facet entries by facet entry count. If <c>false</c> then the facets
+        /// are sorted lexicographically in ascending order.
+        /// </param>
+        /// <returns>grouped facet results</returns>
+        /// <exception cref="IOException">If I/O related errors occur during merging segment grouped facet counts.</exception>
         public GroupedFacetResult MergeSegmentResults(int size, int minCount, bool orderByCount)
         {
             if (segmentFacetCounts != null)
@@ -126,9 +144,9 @@ namespace Lucene.Net.Search.Grouping
             }
         }
 
-        /**
-         * The grouped facet result. Containing grouped facet entries, total count and total missing count.
-         */
+        /// <summary>
+        /// The grouped facet result. Containing grouped facet entries, total count and total missing count.
+        /// </summary>
         public class GroupedFacetResult
         {
             private readonly static IComparer<FacetEntry> orderByCountAndValue = new OrderByCountAndValueComparer();
@@ -175,14 +193,13 @@ namespace Lucene.Net.Search.Grouping
                 }
             }
 
-            /**
-             * Returns a list of facet entries to be rendered based on the specified offset and limit.
-             * The facet entries are retrieved from the facet entries collected during merging.
-             *
-             * @param offset The offset in the collected facet entries during merging
-             * @param limit The number of facets to return starting from the offset.
-             * @return a list of facet entries to be rendered based on the specified offset and limit
-             */
+            /// <summary>
+            /// Returns a list of facet entries to be rendered based on the specified offset and limit.
+            /// The facet entries are retrieved from the facet entries collected during merging.
+            /// </summary>
+            /// <param name="offset">The offset in the collected facet entries during merging</param>
+            /// <param name="limit">The number of facets to return starting from the offset.</param>
+            /// <returns>a list of facet entries to be rendered based on the specified offset and limit</returns>
             public List<FacetEntry> GetFacetEntries(int offset, int limit)
             {
                 List<FacetEntry> entries = new List<FacetEntry>();
@@ -205,11 +222,9 @@ namespace Lucene.Net.Search.Grouping
                 return entries;
             }
 
-            /**
-             * Returns the sum of all facet entries counts.
-             *
-             * @return the sum of all facet entries counts
-             */
+            /// <summary>
+            /// Gets the sum of all facet entries counts.
+            /// </summary>
             public int TotalCount
             {
                 get
@@ -218,11 +233,9 @@ namespace Lucene.Net.Search.Grouping
                 }
             }
 
-            /**
-             * Returns the number of groups that didn't have a facet value.
-             *
-             * @return the number of groups that didn't have a facet value
-             */
+            /// <summary>
+            /// Gets the number of groups that didn't have a facet value.
+            /// </summary>
             public int TotalMissingCount
             {
                 get
@@ -232,9 +245,9 @@ namespace Lucene.Net.Search.Grouping
             }
         }
 
-        /**
-         * Represents a facet entry with a value and a count.
-         */
+        /// <summary>
+        /// Represents a facet entry with a value and a count.
+        /// </summary>
         public class FacetEntry
         {
 
@@ -275,9 +288,9 @@ namespace Lucene.Net.Search.Grouping
                     '}';
             }
 
-            /**
-             * @return The value of this facet entry
-             */
+            /// <summary>
+            /// Gets the value of this facet entry
+            /// </summary>
             public BytesRef Value
             {
                 get
@@ -286,9 +299,9 @@ namespace Lucene.Net.Search.Grouping
                 }
             }
 
-            /**
-             * @return The count (number of groups) of this facet entry.
-             */
+            /// <summary>
+            /// Gets the count (number of groups) of this facet entry.
+            /// </summary>
             public int Count
             {
                 get
@@ -298,10 +311,14 @@ namespace Lucene.Net.Search.Grouping
             }
         }
 
-        /**
-         * Contains the local grouped segment counts for a particular segment.
-         * Each <code>SegmentResult</code> must be added together.
-         */
+        /// <summary>
+        /// Contains the local grouped segment counts for a particular segment.
+        /// Each <see cref="AbstractSegmentResult"/> must be added together.
+        /// </summary>
+        /// <remarks>
+        /// LUCENENET NOTE: Renamed from SegmentResult to AbstractSegmentResult
+        /// to avoid naming conflicts with subclasses.
+        /// </remarks>
         protected internal abstract class AbstractSegmentResult
         {
             protected internal readonly int[] counts;
@@ -320,11 +337,10 @@ namespace Lucene.Net.Search.Grouping
                 this.maxTermPos = maxTermPos;
             }
 
-            /**
-             * Go to next term in this <code>SegmentResult</code> in order to retrieve the grouped facet counts.
-             *
-             * @throws IOException If I/O related errors occur
-             */
+            /// <summary>
+            /// Go to next term in this <see cref="AbstractSegmentResult"/> in order to retrieve the grouped facet counts.
+            /// </summary>
+            /// <exception cref="IOException">If I/O related errors occur</exception>
             protected internal abstract void NextTerm();
 
         }

http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/AbstractSecondPassGroupingCollector.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/AbstractSecondPassGroupingCollector.cs b/src/Lucene.Net.Grouping/AbstractSecondPassGroupingCollector.cs
index de3feb6..e8aedc8 100644
--- a/src/Lucene.Net.Grouping/AbstractSecondPassGroupingCollector.cs
+++ b/src/Lucene.Net.Grouping/AbstractSecondPassGroupingCollector.cs
@@ -6,6 +6,23 @@ using System.Linq;
 
 namespace Lucene.Net.Search.Grouping
 {
+    /*
+	 * Licensed to the Apache Software Foundation (ASF) under one or more
+	 * contributor license agreements.  See the NOTICE file distributed with
+	 * this work for additional information regarding copyright ownership.
+	 * The ASF licenses this file to You under the Apache License, Version 2.0
+	 * (the "License"); you may not use this file except in compliance with
+	 * the License.  You may obtain a copy of the License at
+	 *
+	 *     http://www.apache.org/licenses/LICENSE-2.0
+	 *
+	 * Unless required by applicable law or agreed to in writing, software
+	 * distributed under the License is distributed on an "AS IS" BASIS,
+	 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	 * See the License for the specific language governing permissions and
+	 * limitations under the License.
+	 */
+
     /// <summary>
     /// SecondPassGroupingCollector is the second of two passes
     /// necessary to collect grouped docs.  This pass gathers the
@@ -13,7 +30,7 @@ namespace Lucene.Net.Search.Grouping
     /// first pass. Concrete subclasses define what a group is and how it
     /// is internally collected.
     /// <para>
-    /// See {@link org.apache.lucene.search.grouping} for more
+    /// See <a href="https://github.com/apache/lucene-solr/blob/releases/lucene-solr/4.8.0/lucene/grouping/src/java/org/apache/lucene/search/grouping/package.html">org.apache.lucene.search.grouping</a> for more
     /// details including a full code example.
     /// </para>
     /// @lucene.experimental
@@ -87,13 +104,12 @@ namespace Lucene.Net.Search.Grouping
             }
         }
 
-        /**
-         * Returns the group the specified doc belongs to or <code>null</code> if no group could be retrieved.
-         *
-         * @param doc The specified doc
-         * @return the group the specified doc belongs to or <code>null</code> if no group could be retrieved
-         * @throws IOException If an I/O related error occurred
-         */
+        /// <summary>
+        /// Returns the group the specified doc belongs to or <c>null</c> if no group could be retrieved.
+        /// </summary>
+        /// <param name="doc">The specified doc</param>
+        /// <returns>the group the specified doc belongs to or <c>null</c> if no group could be retrieved</returns>
+        /// <exception cref="IOException">If an I/O related error occurred</exception>
         protected abstract AbstractSecondPassGroupingCollector.SearchGroupDocs<TGroupValue> RetrieveGroup(int doc);
 
         public override AtomicReaderContext NextReader
@@ -142,6 +158,11 @@ namespace Lucene.Net.Search.Grouping
         
     }
 
+    /// <summary>
+    /// LUCENENET specific class used to simulate the syntax used 
+    /// to access nested classes of <see cref="AbstractAllGroupHeadsCollector{GH}"/>
+    /// without referencing the generic closing type.
+    /// </summary>
     public class AbstractSecondPassGroupingCollector
     {
         /// <summary>
@@ -166,6 +187,7 @@ namespace Lucene.Net.Search.Grouping
 
     /// <summary>
     /// LUCENENET specific interface used to apply covariance to TGroupValue
+    /// to simulate Java's wildcard generics.
     /// </summary>
     /// <typeparam name="TGroupValue"></typeparam>
     public interface IAbstractSecondPassGroupingCollector<out TGroupValue>

http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/BlockGroupingCollector.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/BlockGroupingCollector.cs b/src/Lucene.Net.Grouping/BlockGroupingCollector.cs
index c7fd34c..0f3549f 100644
--- a/src/Lucene.Net.Grouping/BlockGroupingCollector.cs
+++ b/src/Lucene.Net.Grouping/BlockGroupingCollector.cs
@@ -6,6 +6,23 @@ using System.Diagnostics;
 
 namespace Lucene.Net.Search.Grouping
 {
+    /*
+	 * Licensed to the Apache Software Foundation (ASF) under one or more
+	 * contributor license agreements.  See the NOTICE file distributed with
+	 * this work for additional information regarding copyright ownership.
+	 * The ASF licenses this file to You under the Apache License, Version 2.0
+	 * (the "License"); you may not use this file except in compliance with
+	 * the License.  You may obtain a copy of the License at
+	 *
+	 *     http://www.apache.org/licenses/LICENSE-2.0
+	 *
+	 * Unless required by applicable law or agreed to in writing, software
+	 * distributed under the License is distributed on an "AS IS" BASIS,
+	 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	 * See the License for the specific language governing permissions and
+	 * limitations under the License.
+	 */
+
     // TODO: this sentence is too long for the class summary.
     /// <summary>
     /// BlockGroupingCollector performs grouping with a
@@ -32,7 +49,7 @@ namespace Lucene.Net.Search.Grouping
     /// you to ensure this was the case.
     /// </para>
     /// <para>
-    /// See {@link org.apache.lucene.search.grouping} for more
+    /// See <a href="https://github.com/apache/lucene-solr/blob/releases/lucene-solr/4.8.0/lucene/grouping/src/java/org/apache/lucene/search/grouping/package.html">org.apache.lucene.search.grouping</a> for more
     /// details including a full code example.
     /// </para>
     /// @lucene.experimental
@@ -247,24 +264,28 @@ namespace Lucene.Net.Search.Grouping
             subDocUpto = 0;
         }
 
-        /**
-         * Create the single pass collector.
-         *
-         *  @param groupSort The {@link Sort} used to sort the
-         *    groups.  The top sorted document within each group
-         *    according to groupSort, determines how that group
-         *    sorts against other groups.  This must be non-null,
-         *    ie, if you want to groupSort by relevance use
-         *    Sort.RELEVANCE.
-         *  @param topNGroups How many top groups to keep.
-         *  @param needsScores true if the collected documents
-         *    require scores, either because relevance is included
-         *    in the withinGroupSort or because you plan to pass true
-         *    for either getSscores or getMaxScores to {@link
-         *    #getTopGroups}
-         *  @param lastDocPerGroup a {@link Filter} that marks the
-         *    last document in each group.
-         */
+        /// <summary>
+        /// Create the single pass collector.
+        /// </summary>
+        /// <param name="groupSort">
+        /// The <see cref="Sort"/> used to sort the
+        /// groups.  The top sorted document within each group
+        /// according to groupSort, determines how that group
+        /// sorts against other groups.  This must be non-null,
+        /// ie, if you want to groupSort by relevance use
+        /// <see cref="Sort.RELEVANCE"/>.
+        /// </param>
+        /// <param name="topNGroups">How many top groups to keep.</param>
+        /// <param name="needsScores">
+        /// true if the collected documents
+        /// require scores, either because relevance is included
+        /// in the withinGroupSort or because you plan to pass true
+        /// for either GetScores or GetMaxScores to <see cref="GetTopGroups(Sort, int, int, int, bool)"/>
+        /// </param>
+        /// <param name="lastDocPerGroup">
+        /// a <see cref="Filter"/> that marks the
+        /// last document in each group.
+        /// </param>
         public BlockGroupingCollector(Sort groupSort, int topNGroups, bool needsScores, Filter lastDocPerGroup)
         {
 
@@ -305,32 +326,68 @@ namespace Lucene.Net.Search.Grouping
         // typically they will be presented as a "single" result
         // in the UI?
 
-        /** Returns the grouped results.  Returns null if the
-         *  number of groups collected is <= groupOffset.
-         *
-         *  <p><b>NOTE</b>: This collector is unable to compute
-         *  the groupValue per group so it will always be null.
-         *  This is normally not a problem, as you can obtain the
-         *  value just like you obtain other values for each
-         *  matching document (eg, via stored fields, via
-         *  FieldCache, etc.)
-         *
-         *  @param withinGroupSort The {@link Sort} used to sort
-         *    documents within each group.  Passing null is
-         *    allowed, to sort by relevance.
-         *  @param groupOffset Which group to start from
-         *  @param withinGroupOffset Which document to start from
-         *    within each group
-         *  @param maxDocsPerGroup How many top documents to keep
-         *     within each group.
-         *  @param fillSortFields If true then the Comparable
-         *     values for the sort fields will be set
-         */
+        /// <summary>
+        /// Returns the grouped results.  Returns null if the
+        /// number of groups collected is &lt;= groupOffset.
+        /// 
+        /// <para>
+        /// <b>NOTE</b>: This collector is unable to compute
+        /// the groupValue per group so it will always be null.
+        /// This is normally not a problem, as you can obtain the
+        /// value just like you obtain other values for each
+        /// matching document (eg, via stored fields, via
+        /// FieldCache, etc.)
+        /// </para>
+        /// </summary>
+        /// <param name="withinGroupSort">
+        /// The <see cref="Sort"/> used to sort
+        /// documents within each group.  Passing null is
+        /// allowed, to sort by relevance.
+        /// </param>
+        /// <param name="groupOffset">Which group to start from</param>
+        /// <param name="withinGroupOffset">
+        /// Which document to start from within each group
+        /// </param>
+        /// <param name="maxDocsPerGroup">
+        /// How many top documents to keep within each group.
+        /// </param>
+        /// <param name="fillSortFields">
+        /// If true then the Comparable values for the sort fields will be set
+        /// </param>
         public ITopGroups<object> GetTopGroups(Sort withinGroupSort, int groupOffset, int withinGroupOffset, int maxDocsPerGroup, bool fillSortFields)
         {
             return GetTopGroups<object>(withinGroupSort, groupOffset, withinGroupOffset, maxDocsPerGroup, fillSortFields);
         }
 
+        /// <summary>
+        /// Returns the grouped results.  Returns null if the
+        /// number of groups collected is &lt;= groupOffset.
+        /// 
+        /// <para>
+        /// <b>NOTE</b>: This collector is unable to compute
+        /// the groupValue per group so it will always be null.
+        /// This is normally not a problem, as you can obtain the
+        /// value just like you obtain other values for each
+        /// matching document (eg, via stored fields, via
+        /// FieldCache, etc.)
+        /// </para>
+        /// </summary>
+        /// <typeparam name="TGroupValue">The expected return type for group value</typeparam>
+        /// <<param name="withinGroupSort">
+        /// The <see cref="Sort"/> used to sort
+        /// documents within each group.  Passing null is
+        /// allowed, to sort by relevance.
+        /// </param>
+        /// <param name="groupOffset">Which group to start from</param>
+        /// <param name="withinGroupOffset">
+        /// Which document to start from within each group
+        /// </param>
+        /// <param name="maxDocsPerGroup">
+        /// How many top documents to keep within each group.
+        /// </param>
+        /// <param name="fillSortFields">
+        /// If true then the Comparable values for the sort fields will be set
+        /// </param>
         public ITopGroups<TGroupValue> GetTopGroups<TGroupValue>(Sort withinGroupSort, int groupOffset, int withinGroupOffset, int maxDocsPerGroup, bool fillSortFields)
         {
 
@@ -595,7 +652,6 @@ namespace Lucene.Net.Search.Grouping
                 {
                     comparators[i] = comparators[i].SetNextReader(value);
                 }
-
             }
         }
     }

http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/CollectedSearchGroup.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/CollectedSearchGroup.cs b/src/Lucene.Net.Grouping/CollectedSearchGroup.cs
index 51a905f..39e0d92 100644
--- a/src/Lucene.Net.Grouping/CollectedSearchGroup.cs
+++ b/src/Lucene.Net.Grouping/CollectedSearchGroup.cs
@@ -1,8 +1,25 @@
 ´╗┐namespace Lucene.Net.Search.Grouping
 {
+    /*
+	 * Licensed to the Apache Software Foundation (ASF) under one or more
+	 * contributor license agreements.  See the NOTICE file distributed with
+	 * this work for additional information regarding copyright ownership.
+	 * The ASF licenses this file to You under the Apache License, Version 2.0
+	 * (the "License"); you may not use this file except in compliance with
+	 * the License.  You may obtain a copy of the License at
+	 *
+	 *     http://www.apache.org/licenses/LICENSE-2.0
+	 *
+	 * Unless required by applicable law or agreed to in writing, software
+	 * distributed under the License is distributed on an "AS IS" BASIS,
+	 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	 * See the License for the specific language governing permissions and
+	 * limitations under the License.
+	 */
+
     /// <summary>
-    /// Expert: representation of a group in {@link AbstractFirstPassGroupingCollector},
-    /// tracking the top doc and {@link FieldComparator} slot.
+    /// Expert: representation of a group in <see cref="AbstractFirstPassGroupingCollector{TGroupValue}"/>,
+    /// tracking the top doc and <see cref="FieldComparator"/> slot.
     /// @lucene.internal
     /// </summary>
     /// <typeparam name="TGroupValue"></typeparam>

http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/Function/FunctionAllGroupHeadsCollector.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/Function/FunctionAllGroupHeadsCollector.cs b/src/Lucene.Net.Grouping/Function/FunctionAllGroupHeadsCollector.cs
index 70aa484..70a2033 100644
--- a/src/Lucene.Net.Grouping/Function/FunctionAllGroupHeadsCollector.cs
+++ b/src/Lucene.Net.Grouping/Function/FunctionAllGroupHeadsCollector.cs
@@ -6,6 +6,23 @@ using System.Collections.Generic;
 
 namespace Lucene.Net.Search.Grouping.Function
 {
+    /*
+	 * Licensed to the Apache Software Foundation (ASF) under one or more
+	 * contributor license agreements.  See the NOTICE file distributed with
+	 * this work for additional information regarding copyright ownership.
+	 * The ASF licenses this file to You under the Apache License, Version 2.0
+	 * (the "License"); you may not use this file except in compliance with
+	 * the License.  You may obtain a copy of the License at
+	 *
+	 *     http://www.apache.org/licenses/LICENSE-2.0
+	 *
+	 * Unless required by applicable law or agreed to in writing, software
+	 * distributed under the License is distributed on an "AS IS" BASIS,
+	 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	 * See the License for the specific language governing permissions and
+	 * limitations under the License.
+	 */
+
     /// <summary>
     /// An implementation of <see cref="AbstractAllGroupHeadsCollector"/> for retrieving the most relevant groups when grouping
     /// by <see cref="ValueSource"/>.
@@ -24,13 +41,12 @@ namespace Lucene.Net.Search.Grouping.Function
         private AtomicReaderContext readerContext;
         private Scorer scorer;
 
-        /**
-         * Constructs a {@link FunctionAllGroupHeadsCollector} instance.
-         *
-         * @param groupBy The {@link ValueSource} to group by
-         * @param vsContext The ValueSource context
-         * @param sortWithinGroup The sort within a group
-         */
+        /// <summary>
+        /// Constructs a <see cref="FunctionAllGroupHeadsCollector"/> instance.
+        /// </summary>
+        /// <param name="groupBy">The <see cref="ValueSource"/> to group by</param>
+        /// <param name="vsContext">The <see cref="ValueSource"/> context</param>
+        /// <param name="sortWithinGroup">The sort within a group</param>
         public FunctionAllGroupHeadsCollector(ValueSource groupBy, IDictionary /* Map<?, ?> */ vsContext, Sort sortWithinGroup)
             : base(sortWithinGroup.GetSort().Length)
         {
@@ -103,9 +119,11 @@ namespace Lucene.Net.Search.Grouping.Function
             }
         }
 
-        /** Holds current head document for a single group.
-         *
-         * @lucene.experimental */
+        /// <summary>
+        /// Holds current head document for a single group.
+        /// 
+        /// @lucene.experimental
+        /// </summary>
         public class GroupHead : AbstractAllGroupHeadsCollector_GroupHead
         {
 

http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/Function/FunctionAllGroupsCollector.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/Function/FunctionAllGroupsCollector.cs b/src/Lucene.Net.Grouping/Function/FunctionAllGroupsCollector.cs
index c5c7623..be73a9a 100644
--- a/src/Lucene.Net.Grouping/Function/FunctionAllGroupsCollector.cs
+++ b/src/Lucene.Net.Grouping/Function/FunctionAllGroupsCollector.cs
@@ -6,6 +6,23 @@ using System.Collections.Generic;
 
 namespace Lucene.Net.Search.Grouping.Function
 {
+    /*
+	 * Licensed to the Apache Software Foundation (ASF) under one or more
+	 * contributor license agreements.  See the NOTICE file distributed with
+	 * this work for additional information regarding copyright ownership.
+	 * The ASF licenses this file to You under the Apache License, Version 2.0
+	 * (the "License"); you may not use this file except in compliance with
+	 * the License.  You may obtain a copy of the License at
+	 *
+	 *     http://www.apache.org/licenses/LICENSE-2.0
+	 *
+	 * Unless required by applicable law or agreed to in writing, software
+	 * distributed under the License is distributed on an "AS IS" BASIS,
+	 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	 * See the License for the specific language governing permissions and
+	 * limitations under the License.
+	 */
+
     /// <summary>
     /// A collector that collects all groups that match the
     /// query. Only the group value is collected, and the order
@@ -27,12 +44,11 @@ namespace Lucene.Net.Search.Grouping.Function
         private FunctionValues.AbstractValueFiller filler;
         private MutableValue mval;
 
-        /**
-         * Constructs a {@link FunctionAllGroupsCollector} instance.
-         *
-         * @param groupBy The {@link ValueSource} to group by
-         * @param vsContext The ValueSource context
-         */
+        /// <summary>
+        /// Constructs a <see cref="FunctionAllGroupsCollector"/> instance.
+        /// </summary>
+        /// <param name="groupBy">The <see cref="ValueSource"/> to group by</param>
+        /// <param name="vsContext">The <see cref="ValueSource"/> context</param>
         public FunctionAllGroupsCollector(ValueSource groupBy, IDictionary /* Map<?, ?> */ vsContext)
         {
             this.vsContext = vsContext;

http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/Function/FunctionDistinctValuesCollector.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/Function/FunctionDistinctValuesCollector.cs b/src/Lucene.Net.Grouping/Function/FunctionDistinctValuesCollector.cs
index 22f2395..409cc67 100644
--- a/src/Lucene.Net.Grouping/Function/FunctionDistinctValuesCollector.cs
+++ b/src/Lucene.Net.Grouping/Function/FunctionDistinctValuesCollector.cs
@@ -7,6 +7,23 @@ using System.Collections.Generic;
 
 namespace Lucene.Net.Search.Grouping.Function
 {
+    /*
+	 * Licensed to the Apache Software Foundation (ASF) under one or more
+	 * contributor license agreements.  See the NOTICE file distributed with
+	 * this work for additional information regarding copyright ownership.
+	 * The ASF licenses this file to You under the Apache License, Version 2.0
+	 * (the "License"); you may not use this file except in compliance with
+	 * the License.  You may obtain a copy of the License at
+	 *
+	 *     http://www.apache.org/licenses/LICENSE-2.0
+	 *
+	 * Unless required by applicable law or agreed to in writing, software
+	 * distributed under the License is distributed on an "AS IS" BASIS,
+	 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	 * See the License for the specific language governing permissions and
+	 * limitations under the License.
+	 */
+
     /// <summary>
     /// Function based implementation of <see cref="AbstractDistinctValuesCollector"/>.
     /// 
@@ -65,11 +82,11 @@ namespace Lucene.Net.Search.Grouping.Function
             }
         }
 
-
-
-        /** Holds distinct values for a single group.
-         *
-         * @lucene.experimental */
+        /// <summary>
+        /// Holds distinct values for a single group.
+        /// 
+        /// @lucene.experimental
+        /// </summary>
         public class GroupCount : AbstractDistinctValuesCollector.GroupCount<MutableValue>
         {
             internal GroupCount(MutableValue groupValue)

http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/Function/FunctionFirstPassGroupingCollector.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/Function/FunctionFirstPassGroupingCollector.cs b/src/Lucene.Net.Grouping/Function/FunctionFirstPassGroupingCollector.cs
index 18f9fb6..fcf102d 100644
--- a/src/Lucene.Net.Grouping/Function/FunctionFirstPassGroupingCollector.cs
+++ b/src/Lucene.Net.Grouping/Function/FunctionFirstPassGroupingCollector.cs
@@ -5,6 +5,23 @@ using System.Collections;
 
 namespace Lucene.Net.Search.Grouping.Function
 {
+    /*
+	 * Licensed to the Apache Software Foundation (ASF) under one or more
+	 * contributor license agreements.  See the NOTICE file distributed with
+	 * this work for additional information regarding copyright ownership.
+	 * The ASF licenses this file to You under the Apache License, Version 2.0
+	 * (the "License"); you may not use this file except in compliance with
+	 * the License.  You may obtain a copy of the License at
+	 *
+	 *     http://www.apache.org/licenses/LICENSE-2.0
+	 *
+	 * Unless required by applicable law or agreed to in writing, software
+	 * distributed under the License is distributed on an "AS IS" BASIS,
+	 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	 * See the License for the specific language governing permissions and
+	 * limitations under the License.
+	 */
+
     /// <summary>
     /// Concrete implementation of <see cref="AbstractFirstPassGroupingCollector{TGroupValue}"/> that groups based on
     /// <see cref="ValueSource"/> instances.

http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/Function/FunctionSecondPassGroupingCollector.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/Function/FunctionSecondPassGroupingCollector.cs b/src/Lucene.Net.Grouping/Function/FunctionSecondPassGroupingCollector.cs
index ec1fccb..027ea55 100644
--- a/src/Lucene.Net.Grouping/Function/FunctionSecondPassGroupingCollector.cs
+++ b/src/Lucene.Net.Grouping/Function/FunctionSecondPassGroupingCollector.cs
@@ -6,6 +6,23 @@ using System.Collections.Generic;
 
 namespace Lucene.Net.Search.Grouping.Function
 {
+    /*
+	 * Licensed to the Apache Software Foundation (ASF) under one or more
+	 * contributor license agreements.  See the NOTICE file distributed with
+	 * this work for additional information regarding copyright ownership.
+	 * The ASF licenses this file to You under the Apache License, Version 2.0
+	 * (the "License"); you may not use this file except in compliance with
+	 * the License.  You may obtain a copy of the License at
+	 *
+	 *     http://www.apache.org/licenses/LICENSE-2.0
+	 *
+	 * Unless required by applicable law or agreed to in writing, software
+	 * distributed under the License is distributed on an "AS IS" BASIS,
+	 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	 * See the License for the specific language governing permissions and
+	 * limitations under the License.
+	 */
+
     /// <summary>
     /// Concrete implementation of <see cref="AbstractSecondPassGroupingCollector{TGroupValue}"/> that groups based on
     /// <see cref="ValueSource"/> instances.

http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/GroupDocs.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/GroupDocs.cs b/src/Lucene.Net.Grouping/GroupDocs.cs
index cc1a7c6..c997e30 100644
--- a/src/Lucene.Net.Grouping/GroupDocs.cs
+++ b/src/Lucene.Net.Grouping/GroupDocs.cs
@@ -71,6 +71,7 @@ namespace Lucene.Net.Search.Grouping
 
     /// <summary>
     /// LUCENENET specific interface used to apply covariance to TGroupValue
+    /// to simulate Java's wildcard generics.
     /// </summary>
     /// <typeparam name="TGroupValue"></typeparam>
     public interface IGroupDocs<out TGroupValue>

http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/GroupingSearch.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/GroupingSearch.cs b/src/Lucene.Net.Grouping/GroupingSearch.cs
index c9353d8..5bb98c5 100644
--- a/src/Lucene.Net.Grouping/GroupingSearch.cs
+++ b/src/Lucene.Net.Grouping/GroupingSearch.cs
@@ -9,6 +9,23 @@ using System.Collections.Generic;
 
 namespace Lucene.Net.Search.Grouping
 {
+    /*
+	 * Licensed to the Apache Software Foundation (ASF) under one or more
+	 * contributor license agreements.  See the NOTICE file distributed with
+	 * this work for additional information regarding copyright ownership.
+	 * The ASF licenses this file to You under the Apache License, Version 2.0
+	 * (the "License"); you may not use this file except in compliance with
+	 * the License.  You may obtain a copy of the License at
+	 *
+	 *     http://www.apache.org/licenses/LICENSE-2.0
+	 *
+	 * Unless required by applicable law or agreed to in writing, software
+	 * distributed under the License is distributed on an "AS IS" BASIS,
+	 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	 * See the License for the specific language governing permissions and
+	 * limitations under the License.
+	 */
+
     /// <summary>
     /// Convenience class to perform grouping in a non distributed environment.
     /// @lucene.experimental
@@ -39,36 +56,33 @@ namespace Lucene.Net.Search.Grouping
         private ICollection /* Collection<?> */ matchingGroups;
         private Bits matchingGroupHeads;
 
-        /**
-         * Constructs a <code>GroupingSearch</code> instance that groups documents by index terms using the {@link FieldCache}.
-         * The group field can only have one token per document. This means that the field must not be analysed.
-         *
-         * @param groupField The name of the field to group by.
-         */
+        /// <summary>
+        /// Constructs a <see cref="GroupingSearch"/> instance that groups documents by index terms using the <see cref="FieldCache"/>.
+        /// The group field can only have one token per document. This means that the field must not be analysed.
+        /// </summary>
+        /// <param name="groupField">The name of the field to group by.</param>
         public GroupingSearch(string groupField)
             : this(groupField, null, null, null)
         {
         }
 
-        /**
-         * Constructs a <code>GroupingSearch</code> instance that groups documents by function using a {@link ValueSource}
-         * instance.
-         *
-         * @param groupFunction      The function to group by specified as {@link ValueSource}
-         * @param valueSourceContext The context of the specified groupFunction
-         */
+        /// <summary>
+        /// Constructs a <see cref="GroupingSearch"/> instance that groups documents by function using a <see cref="ValueSource"/>
+        /// instance.
+        /// </summary>
+        /// <param name="groupFunction">The function to group by specified as <see cref="ValueSource"/></param>
+        /// <param name="valueSourceContext">The context of the specified groupFunction</param>
         public GroupingSearch(ValueSource groupFunction, IDictionary /* Map<?, ?> */ valueSourceContext)
             : this(null, groupFunction, valueSourceContext, null)
         {
 
         }
 
-        /**
-         * Constructor for grouping documents by doc block.
-         * This constructor can only be used when documents belonging in a group are indexed in one block.
-         *
-         * @param groupEndDocs The filter that marks the last document in all doc blocks
-         */
+        /// <summary>
+        /// Constructor for grouping documents by doc block.
+        /// This constructor can only be used when documents belonging in a group are indexed in one block.
+        /// </summary>
+        /// <param name="groupEndDocs">The filter that marks the last document in all doc blocks</param>
         public GroupingSearch(Filter groupEndDocs)
             : this(null, null, null, groupEndDocs)
         {
@@ -82,37 +96,46 @@ namespace Lucene.Net.Search.Grouping
             this.groupEndDocs = groupEndDocs;
         }
 
-        /**
-         * Executes a grouped search. Both the first pass and second pass are executed on the specified searcher.
-         *
-         * @param searcher    The {@link org.apache.lucene.search.IndexSearcher} instance to execute the grouped search on.
-         * @param query       The query to execute with the grouping
-         * @param groupOffset The group offset
-         * @param groupLimit  The number of groups to return from the specified group offset
-         * @return the grouped result as a {@link TopGroups} instance
-         * @throws IOException If any I/O related errors occur
-         */
+        /// <summary>
+        /// Executes a grouped search. Both the first pass and second pass are executed on the specified searcher.
+        /// </summary>
+        /// <param name="searcher">The <see cref="IndexSearcher"/> instance to execute the grouped search on.</param>
+        /// <param name="query">The query to execute with the grouping</param>
+        /// <param name="groupOffset">The group offset</param>
+        /// <param name="groupLimit">The number of groups to return from the specified group offset</param>
+        /// <returns>the grouped result as a <see cref="ITopGroups{Object}"/> instance</returns>
+        /// <exception cref="IOException">If any I/O related errors occur</exception>
         public ITopGroups<object> Search(IndexSearcher searcher, Query query, int groupOffset, int groupLimit)
         {
             return Search<object>(searcher, null, query, groupOffset, groupLimit);
         }
 
+
+        /// <summary>
+        /// Executes a grouped search. Both the first pass and second pass are executed on the specified searcher.
+        /// </summary>
+        /// <typeparam name="TGroupValue">The expected return type of the search.</typeparam>
+        /// <param name="searcher">The <see cref="IndexSearcher"/> instance to execute the grouped search on.</param>
+        /// <param name="query">The query to execute with the grouping</param>
+        /// <param name="groupOffset">The group offset</param>
+        /// <param name="groupLimit">The number of groups to return from the specified group offset</param>
+        /// <returns>the grouped result as a <see cref="ITopGroups{Object}"/> instance</returns>
+        /// <exception cref="IOException">If any I/O related errors occur</exception>
         public ITopGroups<TGroupValue> Search<TGroupValue>(IndexSearcher searcher, Query query, int groupOffset, int groupLimit)
         {
             return Search<TGroupValue>(searcher, null, query, groupOffset, groupLimit);
         }
 
-        /**
-         * Executes a grouped search. Both the first pass and second pass are executed on the specified searcher.
-         *
-         * @param searcher    The {@link org.apache.lucene.search.IndexSearcher} instance to execute the grouped search on.
-         * @param filter      The filter to execute with the grouping
-         * @param query       The query to execute with the grouping
-         * @param groupOffset The group offset
-         * @param groupLimit  The number of groups to return from the specified group offset
-         * @return the grouped result as a {@link TopGroups} instance
-         * @throws IOException If any I/O related errors occur
-         */
+        /// <summary>
+        /// Executes a grouped search. Both the first pass and second pass are executed on the specified searcher.
+        /// </summary>
+        /// <param name="searcher">The <see cref="IndexSearcher"/> instance to execute the grouped search on.</param>
+        /// <param name="filter">The filter to execute with the grouping</param>
+        /// <param name="query">The query to execute with the grouping</param>
+        /// <param name="groupOffset">The group offset</param>
+        /// <param name="groupLimit">The number of groups to return from the specified group offset</param>
+        /// <returns>the grouped result as a <see cref="ITopGroups{Object}"/> instance</returns>
+        /// <exception cref="IOException">If any I/O related errors occur</exception>
         public ITopGroups<object> Search(IndexSearcher searcher, Filter filter, Query query, int groupOffset, int groupLimit)
         {
             if (groupFunction != null)
@@ -133,6 +156,17 @@ namespace Lucene.Net.Search.Grouping
             }
         }
 
+        /// <summary>
+        /// Executes a grouped search. Both the first pass and second pass are executed on the specified searcher.
+        /// </summary>
+        /// <typeparam name="TGroupValue">The expected return type of the search.</typeparam>
+        /// <param name="searcher">The <see cref="IndexSearcher"/> instance to execute the grouped search on.</param>
+        /// <param name="filter">The filter to execute with the grouping</param>
+        /// <param name="query">The query to execute with the grouping</param>
+        /// <param name="groupOffset">The group offset</param>
+        /// <param name="groupLimit">The number of groups to return from the specified group offset</param>
+        /// <returns>the grouped result as a <see cref="ITopGroups{Object}"/> instance</returns>
+        /// <exception cref="IOException">If any I/O related errors occur</exception>
         public ITopGroups<TGroupValue> Search<TGroupValue>(IndexSearcher searcher, Filter filter, Query query, int groupOffset, int groupLimit)
         {
             if (groupField != null || groupFunction != null)
@@ -149,19 +183,6 @@ namespace Lucene.Net.Search.Grouping
             }
         }
 
-        //protected ITopGroups<object> GroupByFieldOrFunction(IndexSearcher searcher, Filter filter, Query query, int groupOffset, int groupLimit)
-        //{
-        //    // LUCENENET TODO: Perhaps there is a better way to infer type without resorting to hard-coding them here, but
-        //    // the original GroupByFieldOrFunction is already aware of the underlying type based on the FirstPassGroupingCollector
-        //    // and SecondPassGroupingCollector.
-        //    if (groupFunction != null)
-        //    {
-        //        return GroupByFieldOrFunction<MutableValue>(searcher, filter, query, groupOffset, groupLimit);
-        //    }
-
-        //    return GroupByFieldOrFunction<BytesRef>(searcher, filter, query, groupOffset, groupLimit);
-        //}
-
         protected ITopGroups<TGroupValue> GroupByFieldOrFunction<TGroupValue>(IndexSearcher searcher, Filter filter, Query query, int groupOffset, int groupLimit)
         {
             int topN = groupOffset + groupLimit;
@@ -323,15 +344,14 @@ namespace Lucene.Net.Search.Grouping
             return c.GetTopGroups<TGroupValue>(sortWithinGroup, groupOffset, groupDocsOffset, topNInsideGroup, fillSortFields);
         }
 
-        /**
-         * Enables caching for the second pass search. The cache will not grow over a specified limit in MB.
-         * The cache is filled during the first pass searched and then replayed during the second pass searched.
-         * If the cache grows beyond the specified limit, then the cache is purged and not used in the second pass search.
-         *
-         * @param maxCacheRAMMB The maximum amount in MB the cache is allowed to hold
-         * @param cacheScores   Whether to cache the scores
-         * @return <code>this</code>
-         */
+        /// <summary>
+        /// Enables caching for the second pass search. The cache will not grow over a specified limit in MB.
+        /// The cache is filled during the first pass searched and then replayed during the second pass searched.
+        /// If the cache grows beyond the specified limit, then the cache is purged and not used in the second pass search.
+        /// </summary>
+        /// <param name="maxCacheRAMMB">The maximum amount in MB the cache is allowed to hold</param>
+        /// <param name="cacheScores">Whether to cache the scores</param>
+        /// <returns><c>this</c></returns>
         public GroupingSearch SetCachingInMB(double maxCacheRAMMB, bool cacheScores)
         {
             this.maxCacheRAMMB = maxCacheRAMMB;
@@ -340,15 +360,14 @@ namespace Lucene.Net.Search.Grouping
             return this;
         }
 
-        /**
-         * Enables caching for the second pass search. The cache will not contain more than the maximum specified documents.
-         * The cache is filled during the first pass searched and then replayed during the second pass searched.
-         * If the cache grows beyond the specified limit, then the cache is purged and not used in the second pass search.
-         *
-         * @param maxDocsToCache The maximum number of documents the cache is allowed to hold
-         * @param cacheScores    Whether to cache the scores
-         * @return <code>this</code>
-         */
+        /// <summary>
+        /// Enables caching for the second pass search. The cache will not contain more than the maximum specified documents.
+        /// The cache is filled during the first pass searched and then replayed during the second pass searched.
+        /// If the cache grows beyond the specified limit, then the cache is purged and not used in the second pass search.
+        /// </summary>
+        /// <param name="maxDocsToCache">The maximum number of documents the cache is allowed to hold</param>
+        /// <param name="cacheScores">Whether to cache the scores</param>
+        /// <returns><c>this</c></returns>
         public GroupingSearch SetCaching(int maxDocsToCache, bool cacheScores)
         {
             this.maxDocsToCache = maxDocsToCache;
@@ -357,11 +376,10 @@ namespace Lucene.Net.Search.Grouping
             return this;
         }
 
-        /**
-         * Disables any enabled cache.
-         *
-         * @return <code>this</code>
-         */
+        /// <summary>
+        /// Disables any enabled cache.
+        /// </summary>
+        /// <returns><c>this</c></returns>
         public GroupingSearch DisableCaching()
         {
             this.maxCacheRAMMB = null;
@@ -369,163 +387,162 @@ namespace Lucene.Net.Search.Grouping
             return this;
         }
 
-        /**
-         * Specifies how groups are sorted.
-         * Defaults to {@link Sort#RELEVANCE}.
-         *
-         * @param groupSort The sort for the groups.
-         * @return <code>this</code>
-         */
+        /// <summary>
+        /// Specifies how groups are sorted.
+        /// Defaults to <see cref="Sort.RELEVANCE"/>.
+        /// </summary>
+        /// <param name="groupSort">The sort for the groups.</param>
+        /// <returns><c>this</c></returns>
         public GroupingSearch SetGroupSort(Sort groupSort)
         {
             this.groupSort = groupSort;
             return this;
         }
 
-        /**
-         * Specified how documents inside a group are sorted.
-         * Defaults to {@link Sort#RELEVANCE}.
-         *
-         * @param sortWithinGroup The sort for documents inside a group
-         * @return <code>this</code>
-         */
+        /// <summary>
+        /// Specified how documents inside a group are sorted.
+        /// Defaults to <see cref="Sort.RELEVANCE"/>.
+        /// </summary>
+        /// <param name="sortWithinGroup">The sort for documents inside a group</param>
+        /// <returns><c>this</c></returns>
         public GroupingSearch SetSortWithinGroup(Sort sortWithinGroup)
         {
             this.sortWithinGroup = sortWithinGroup;
             return this;
         }
 
-        /**
-         * Specifies the offset for documents inside a group.
-         *
-         * @param groupDocsOffset The offset for documents inside a
-         * @return <code>this</code>
-         */
+        /// <summary>
+        /// Specifies the offset for documents inside a group.
+        /// </summary>
+        /// <param name="groupDocsOffset">The offset for documents inside a</param>
+        /// <returns><c>this</c></returns>
         public GroupingSearch SetGroupDocsOffset(int groupDocsOffset)
         {
             this.groupDocsOffset = groupDocsOffset;
             return this;
         }
 
-        /**
-         * Specifies the number of documents to return inside a group from the specified groupDocsOffset.
-         *
-         * @param groupDocsLimit The number of documents to return inside a group
-         * @return <code>this</code>
-         */
+        /// <summary>
+        /// Specifies the number of documents to return inside a group from the specified groupDocsOffset.
+        /// </summary>
+        /// <param name="groupDocsLimit">The number of documents to return inside a group</param>
+        /// <returns><c>this</c></returns>
         public GroupingSearch SetGroupDocsLimit(int groupDocsLimit)
         {
             this.groupDocsLimit = groupDocsLimit;
             return this;
         }
 
-        /**
-         * Whether to also fill the sort fields per returned group and groups docs.
-         *
-         * @param fillSortFields Whether to also fill the sort fields per returned group and groups docs
-         * @return <code>this</code>
-         */
+        /// <summary>
+        /// Whether to also fill the sort fields per returned group and groups docs.
+        /// </summary>
+        /// <param name="fillSortFields">Whether to also fill the sort fields per returned group and groups docs</param>
+        /// <returns><c>this</c></returns>
         public GroupingSearch SetFillSortFields(bool fillSortFields)
         {
             this.fillSortFields = fillSortFields;
             return this;
         }
 
-        /**
-         * Whether to include the scores per doc inside a group.
-         *
-         * @param includeScores Whether to include the scores per doc inside a group
-         * @return <code>this</code>
-         */
+        /// <summary>
+        /// Whether to include the scores per doc inside a group.
+        /// </summary>
+        /// <param name="includeScores">Whether to include the scores per doc inside a group</param>
+        /// <returns><c>this</c></returns>
         public GroupingSearch SetIncludeScores(bool includeScores)
         {
             this.includeScores = includeScores;
             return this;
         }
 
-        /**
-         * Whether to include the score of the most relevant document per group.
-         *
-         * @param includeMaxScore Whether to include the score of the most relevant document per group
-         * @return <code>this</code>
-         */
+        /// <summary>
+        /// Whether to include the score of the most relevant document per group.
+        /// </summary>
+        /// <param name="includeMaxScore">Whether to include the score of the most relevant document per group</param>
+        /// <returns><c>this</c></returns>
         public GroupingSearch SetIncludeMaxScore(bool includeMaxScore)
         {
             this.includeMaxScore = includeMaxScore;
             return this;
         }
 
-        /**
-         * Whether to also compute all groups matching the query.
-         * This can be used to determine the number of groups, which can be used for accurate pagination.
-         * <p/>
-         * When grouping by doc block the number of groups are automatically included in the {@link TopGroups} and this
-         * option doesn't have any influence.
-         *
-         * @param allGroups to also compute all groups matching the query
-         * @return <code>this</code>
-         */
+        /// <summary>
+        /// Whether to also compute all groups matching the query.
+        /// This can be used to determine the number of groups, which can be used for accurate pagination.
+        /// <para>
+        /// When grouping by doc block the number of groups are automatically included in the <see cref="TopGroups"/> and this
+        /// option doesn't have any influence.
+        /// </para>
+        /// </summary>
+        /// <param name="allGroups">to also compute all groups matching the query</param>
+        /// <returns><c>this</c></returns>
         public GroupingSearch SetAllGroups(bool allGroups)
         {
             this.allGroups = allGroups;
             return this;
         }
 
-        /**
-         * If {@link #setAllGroups(boolean)} was set to <code>true</code> then all matching groups are returned, otherwise
-         * an empty collection is returned.
-         *
-         * @param <T> The group value type. This can be a {@link BytesRef} or a {@link MutableValue} instance. If grouping
-         *            by doc block this the group value is always <code>null</code>.
-         * @return all matching groups are returned, or an empty collection
-         */
+        /// <summary>
+        /// If <see cref="SetAllGroups(bool)"/> was set to <c>true</c> then all matching groups are returned, otherwise
+        /// an empty collection is returned.
+        /// </summary>
+        /// <typeparam name="T">The group value type. This can be a <see cref="BytesRef"/> or a <see cref="MutableValue"/> instance. 
+        /// If grouping by doc block this the group value is always <c>null</c>.</typeparam>
+        /// <returns>all matching groups are returned, or an empty collection</returns>
         public ICollection<T> GetAllMatchingGroups<T>()
         {
             return (ICollection<T>)matchingGroups;
         }
 
-        // LUCENENET specific used to get the groups if the type is unknown (since the above
-        // method will crash if the wrong type is used)
+        /// <summary>
+        /// If <see cref="SetAllGroups(bool)"/> was set to <c>true</c> then all matching groups are returned, otherwise
+        /// an empty collection is returned.
+        /// </summary>
+        /// <returns>all matching groups are returned, or an empty collection</returns>
+        /// <remarks>
+        /// LUCENENET specific used to get the groups if the type is unknown or if the code expects
+        /// any type, since <see cref="GetAllMatchingGroups{T}"/>
+        /// will throw an exception if the return type is incorrect.
+        /// </remarks>
         public ICollection GetAllMatchingGroups()
         {
             return matchingGroups;
         }
 
-        /**
-         * Whether to compute all group heads (most relevant document per group) matching the query.
-         * <p/>
-         * This feature isn't enabled when grouping by doc block.
-         *
-         * @param allGroupHeads Whether to compute all group heads (most relevant document per group) matching the query
-         * @return <code>this</code>
-         */
+        /// <summary>
+        /// Whether to compute all group heads (most relevant document per group) matching the query.
+        /// <para>
+        /// This feature isn't enabled when grouping by doc block.
+        /// </para>
+        /// </summary>
+        /// <param name="allGroupHeads">Whether to compute all group heads (most relevant document per group) matching the query</param>
+        /// <returns><c>this</c></returns>
         public GroupingSearch SetAllGroupHeads(bool allGroupHeads)
         {
             this.allGroupHeads = allGroupHeads;
             return this;
         }
 
-        /**
-         * Returns the matching group heads if {@link #setAllGroupHeads(boolean)} was set to true or an empty bit set.
-         *
-         * @return The matching group heads if {@link #setAllGroupHeads(boolean)} was set to true or an empty bit set
-         */
+        /// <summary>
+        /// Returns the matching group heads if <see cref="SetAllGroupHeads(bool)"/> was set to true or an empty bit set.
+        /// </summary>
+        /// <returns>The matching group heads if <see cref="SetAllGroupHeads(bool)"/> was set to true or an empty bit set</returns>
         public Bits GetAllGroupHeads()
         {
             return matchingGroupHeads;
         }
 
-        /**
-         * Sets the initial size of some internal used data structures.
-         * This prevents growing data structures many times. This can improve the performance of the grouping at the cost of
-         * more initial RAM.
-         * <p/>
-         * The {@link #setAllGroups} and {@link #setAllGroupHeads} features use this option.
-         * Defaults to 128.
-         *
-         * @param initialSize The initial size of some internal used data structures
-         * @return <code>this</code>
-         */
+        /// <summary>
+        /// Sets the initial size of some internal used data structures.
+        /// This prevents growing data structures many times. This can improve the performance of the grouping at the cost of
+        /// more initial RAM.
+        /// <para>
+        /// The <see cref="SetAllGroups(bool)"/> and <see cref="SetAllGroupHeads(bool)"/> features use this option.
+        /// Defaults to 128.
+        /// </para>
+        /// </summary>
+        /// <param name="initialSize">The initial size of some internal used data structures</param>
+        /// <returns><c>this</c></returns>
         public GroupingSearch SetInitialSize(int initialSize)
         {
             this.initialSize = initialSize;

http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/SearchGroup.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/SearchGroup.cs b/src/Lucene.Net.Grouping/SearchGroup.cs
index 23140bc..bbf2082 100644
--- a/src/Lucene.Net.Grouping/SearchGroup.cs
+++ b/src/Lucene.Net.Grouping/SearchGroup.cs
@@ -6,21 +6,43 @@ using System.Linq;
 
 namespace Lucene.Net.Search.Grouping
 {
+    /*
+	 * Licensed to the Apache Software Foundation (ASF) under one or more
+	 * contributor license agreements.  See the NOTICE file distributed with
+	 * this work for additional information regarding copyright ownership.
+	 * The ASF licenses this file to You under the Apache License, Version 2.0
+	 * (the "License"); you may not use this file except in compliance with
+	 * the License.  You may obtain a copy of the License at
+	 *
+	 *     http://www.apache.org/licenses/LICENSE-2.0
+	 *
+	 * Unless required by applicable law or agreed to in writing, software
+	 * distributed under the License is distributed on an "AS IS" BASIS,
+	 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	 * See the License for the specific language governing permissions and
+	 * limitations under the License.
+	 */
+
     /// <summary>
     /// Represents a group that is found during the first pass search.
+    /// 
     /// @lucene.experimental
     /// </summary>
     /// <typeparam name="TGroupValue"></typeparam>
     public class SearchGroup<TGroupValue> : ISearchGroup<TGroupValue>
     {
-        /** The value that defines this group  */
+        /// <summary>
+        /// The value that defines this group 
+        /// </summary>
         public TGroupValue GroupValue { get; set; }
 
-        /** The sort values used during sorting. These are the
-         *  groupSort field values of the highest rank document
-         *  (by the groupSort) within the group.  Can be
-         * <code>null</code> if <code>fillFields=false</code> had
-         * been passed to {@link AbstractFirstPassGroupingCollector#getTopGroups} */
+        /// <summary>
+        /// The sort values used during sorting. These are the
+        /// groupSort field values of the highest rank document
+        /// (by the groupSort) within the group.  Can be
+        /// <c>null</c> if <c>fillFields=false</c> had
+        /// been passed to <see cref="AbstractFirstPassGroupingCollector{TGroupValue}.GetTopGroups(int, bool)"/>
+        /// </summary>
         public object[] SortValues { get; set; }
 
         public override string ToString()
@@ -96,7 +118,10 @@ namespace Lucene.Net.Search.Grouping
             }
         }
 
-        // Holds all shards currently on the same group
+        /// <summary>
+        /// Holds all shards currently on the same group
+        /// </summary>
+        /// <typeparam name="T"></typeparam>
         private class MergedGroup<T>
         {
 
@@ -373,16 +398,17 @@ namespace Lucene.Net.Search.Grouping
             }
         }
 
-
-        /** Merges multiple collections of top groups, for example
-         *  obtained from separate index shards.  The provided
-         *  groupSort must match how the groups were sorted, and
-         *  the provided SearchGroups must have been computed
-         *  with fillFields=true passed to {@link
-         *  AbstractFirstPassGroupingCollector#getTopGroups}.
-         *
-         * <p>NOTE: this returns null if the topGroups is empty.
-         */
+        /// <summary>
+        /// Merges multiple collections of top groups, for example
+        /// obtained from separate index shards.  The provided
+        /// groupSort must match how the groups were sorted, and
+        /// the provided SearchGroups must have been computed
+        /// with <c>fillFields=true</c> passed to
+        /// <see cref="AbstractFirstPassGroupingCollector{TGroupValue}.GetTopGroups(int, bool)"/>.
+        /// <para>
+        /// NOTE: this returns null if the topGroups is empty.
+        /// </para>
+        /// </summary>
         public static ICollection<SearchGroup<T>> Merge<T>(IList<IEnumerable<ISearchGroup<T>>> topGroups, int offset, int topN, Sort groupSort)
         {
             if (topGroups.Count == 0)
@@ -399,12 +425,23 @@ namespace Lucene.Net.Search.Grouping
 
     /// <summary>
     /// LUCENENET specific interface used to provide covariance
-    /// with the TGroupValue type
+    /// with the TGroupValue type to simulate Java's wildcard generics.
     /// </summary>
     /// <typeparam name="TGroupValue"></typeparam>
     public interface ISearchGroup<out TGroupValue>
     {
+        /// <summary>
+        /// The value that defines this group 
+        /// </summary>
         TGroupValue GroupValue { get; }
+
+        /// <summary>
+        /// The sort values used during sorting. These are the
+        /// groupSort field values of the highest rank document
+        /// (by the groupSort) within the group.  Can be
+        /// <c>null</c> if <c>fillFields=false</c> had
+        /// been passed to <see cref="AbstractFirstPassGroupingCollector{TGroupValue}.GetTopGroups(int, bool)"/>
+        /// </summary>
         object[] SortValues { get; set; }
     }
 }


Mime
View raw message