Merge pull request #961 from apache/issue/911

Docfx Documentation Fixes, Upgrade docfx, Cross-platform support

.config/dotnet-tools.json

@@ -0,0 +1,13 @@
+{
+  "version": 1,
+  "isRoot": true,
+  "tools": {
+    "docfx": {
+      "version": "2.77.0",
+      "commands": [
+        "docfx"
+      ],
+      "rollForward": false
+    }
+  }
+}

.github/workflows/Lucene-Net-Documentation.yml

@@ -121,7 +121,12 @@ jobs:
       - name: Setup .NET 6 SDK
         uses: actions/setup-dotnet@v3
         with:
-          dotnet-version: '6.0.101'
+          dotnet-version: '6.0.x'
+
+      - name: Setup .NET 8 SDK
+        uses: actions/setup-dotnet@v3
+        with:
+          dotnet-version: '8.0.x'
 
       - name: Build docs
         run: ./main-repo/websites/apidocs/docs.ps1 -Clean -LuceneNetVersion ${{ env.RELEASE_VERSION }}

.vscode/settings.json

@@ -1,7 +1,6 @@
 {
     "files.exclude": {
-        "**/.git": true,
-        "**/docs": true
+        "**/.git": true
     },
     "dotnet-test-explorer.testProjectPath": "src/**/*.Tests.*.csproj"
-}
+}

Lucene.Net.sln

@@ -7,9 +7,9 @@ Microsoft Visual Studio Solution File, Format Version 12.00
 # 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
@@ -282,6 +282,10 @@ Project("{E24C65DC-7377-472B-9ABA-BC803B73C61A}") = "websites", "websites\", "{8
 		SlnRelativePath = "websites\"
 	EndProjectSection
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{42599646-275F-4970-BC60-A3349F6498CC}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "LuceneDocsPlugins", "src\docs\LuceneDocsPlugins\LuceneDocsPlugins.csproj", "{FED4A824-1F32-4948-8D37-2B7610804DB5}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -554,6 +558,10 @@ Global
 		{9880B87D-8D14-476B-B093-9C3AA0DA8B24}.Release|Any CPU.Build.0 = Release|Any CPU
 		{8988CDA4-8420-4BEE-869A-66825055EED2}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{8988CDA4-8420-4BEE-869A-66825055EED2}.Release|Any CPU.ActiveCfg = Debug|Any CPU
+		{FED4A824-1F32-4948-8D37-2B7610804DB5}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{FED4A824-1F32-4948-8D37-2B7610804DB5}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{FED4A824-1F32-4948-8D37-2B7610804DB5}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{FED4A824-1F32-4948-8D37-2B7610804DB5}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -574,6 +582,7 @@ Global
 		{5CD4D4E8-6132-4384-98FC-6AB1C97E0B80} = {8CA61D33-3590-4024-A304-7B1F75B50653}
 		{E5E8C5DC-7048-4818-B884-FB2D037D2EF2} = {8CA61D33-3590-4024-A304-7B1F75B50653}
 		{4D0ED7D9-ABEE-4890-B06C-477E3A32B9A0} = {E5E8C5DC-7048-4818-B884-FB2D037D2EF2}
+		{FED4A824-1F32-4948-8D37-2B7610804DB5} = {42599646-275F-4970-BC60-A3349F6498CC}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {9F2179CC-CFD2-4419-AB74-D72856931F36}

src/Lucene.Net.Analysis.Common/Analysis/Util/CharArrayMap.cs

@@ -162,7 +162,7 @@ public CharArrayDictionary(LuceneVersion matchVersion, int capacity, bool ignore
         /// <param name="matchVersion">
         ///          compatibility match version see <see cref="CharArrayDictionary{TValue}"/> for details. </param>
         /// <param name="collection">
-        ///          a dictionary (<see cref="T:IDictionary{string, V}"/>) whose mappings to be copied. </param>
+        ///          a dictionary (<see cref="T:IDictionary{string,V}"/>) whose mappings to be copied. </param>
         /// <param name="ignoreCase">
         ///          <c>false</c> if and only if the set should be case sensitive;
         ///          otherwise <c>true</c>. </param>
@@ -191,7 +191,7 @@ public CharArrayDictionary(LuceneVersion matchVersion, IDictionary<string, TValu
         /// <param name="matchVersion">
         ///          compatibility match version see <see cref="CharArrayDictionary{TValue}"/> for details. </param>
         /// <param name="collection">
-        ///          a dictionary (<see cref="T:IDictionary{char[], V}"/>) whose mappings to be copied. </param>
+        ///          a dictionary (<see cref="T:IDictionary{char[],V}"/>) whose mappings to be copied. </param>
         /// <param name="ignoreCase">
         ///          <c>false</c> if and only if the set should be case sensitive;
         ///          otherwise <c>true</c>. </param>
@@ -220,7 +220,7 @@ public CharArrayDictionary(LuceneVersion matchVersion, IDictionary<char[], TValu
         /// <param name="matchVersion">
         ///          compatibility match version see <see cref="CharArrayDictionary{TValue}"/> for details. </param>
         /// <param name="collection">
-        ///          a dictionary (<see cref="T:IDictionary{ICharSequence, V}"/>) whose mappings to be copied. </param>
+        ///          a dictionary (<see cref="T:IDictionary{ICharSequence,V}"/>) whose mappings to be copied. </param>
         /// <param name="ignoreCase">
         ///          <c>false</c> if and only if the set should be case sensitive;
         ///          otherwise <c>true</c>. </param>
@@ -1754,7 +1754,7 @@ private bool Equals(string text1, char[] text2)
         /// LUCENENET Specific - test for value equality similar to how it is done in Java
         /// </summary>
         /// <param name="obj">Another dictionary to test the values of</param>
-        /// <returns><c>true</c> if the given object is an <see cref="T:IDictionary{object, V}"/> that contains
+        /// <returns><c>true</c> if the given object is an <see cref="T:IDictionary{object,V}"/> that contains
         /// the same text value pairs as the current dictionary</returns>
         public override bool Equals(object? obj)
         {

src/Lucene.Net.Analysis.OpenNLP/overview.md

@@ -27,7 +27,7 @@ This module exposes functionality from Apache OpenNLP to Apache Lucene.NET. The
 
 For an introduction to Lucene's analysis API, see the [Lucene.Net.Analysis](../core/Lucene.Net.Analysis.html) namespace documentation.
 
-The OpenNLP Tokenizer behavior is similar to the <xref:Lucene.Net.Analysis.Core.WhiteSpaceTokenizer> but is smart about inter-word punctuation. The term stream looks very much like the way you parse words and punctuation while reading. The major difference between this tokenizer and most other tokenizers shipped with Lucene is that punctuation is tokenized. This is required for the following taggers to operate properly.
+The OpenNLP Tokenizer behavior is similar to the <xref:Lucene.Net.Analysis.Core.WhitespaceTokenizer> but is smart about inter-word punctuation. The term stream looks very much like the way you parse words and punctuation while reading. The major difference between this tokenizer and most other tokenizers shipped with Lucene is that punctuation is tokenized. This is required for the following taggers to operate properly.
 
 The OpenNLP taggers annotate terms using the <xref:Lucene.Net.Analysis.TokenAttributes.ITypeAttribute>.
 
@@ -46,7 +46,8 @@ When a `<PackageReference>` is included for this NuGet package in your SDK-style
 
 The `<MavenReference>` item group operates similar to a dependency in Maven. All transitive dependencies are collected and resolved, and then the final output is produced. However, unlike `PackageReference`s, `MavenReference`s are collected by the final output project, and reassessed. That is, each dependent Project within your .NET SDK-style solution contributes its `MavenReference`s to project(s) which include it, and each project makes its own dependency graph. Projects do not contribute their final built assemblies up. They only contribute their dependencies. Allowing each project in a complicated solution to make its own local conflict resolution attempt.
 
-> **NOTE** `<MavenReference>` is only supported on SDK-style MSBuild projects.
+> [!NOTE]
+> `<MavenReference>` is only supported on SDK-style MSBuild projects.
 
 ## MavenReference Example
 

src/Lucene.Net.Highlighter/Highlight/WeightedSpanTermExtractor.cs

@@ -58,7 +58,7 @@ public WeightedSpanTermExtractor(string defaultField)
         }
 
         /// <summary>
-        /// Fills a <see cref="T:IDictionary{string, WeightedSpanTerm}"/> with <see cref="WeightedSpanTerm"/>s using the terms from the supplied <paramref name="query"/>.
+        /// Fills a <see cref="T:IDictionary{string,WeightedSpanTerm}"/> with <see cref="WeightedSpanTerm"/>s using the terms from the supplied <paramref name="query"/>.
         /// </summary>
         /// <param name="query"><see cref="Query"/> to extract Terms from</param>
         /// <param name="terms">Map to place created <see cref="WeightedSpanTerm"/>s in</param>
@@ -237,9 +237,9 @@ protected virtual void ExtractUnknownQuery(Query query,
         }
 
         /// <summary>
-        /// Fills a <see cref="T:IDictionary{string, WeightedSpanTerm}"/> with <see cref="WeightedSpanTerm"/>s using the terms from the supplied <see cref="SpanQuery"/>.
+        /// Fills a <see cref="T:IDictionary{string,WeightedSpanTerm}"/> with <see cref="WeightedSpanTerm"/>s using the terms from the supplied <see cref="SpanQuery"/>.
         /// </summary>
-        /// <param name="terms"><see cref="T:IDictionary{string, WeightedSpanTerm}"/> to place created <see cref="WeightedSpanTerm"/>s in</param>
+        /// <param name="terms"><see cref="T:IDictionary{string,WeightedSpanTerm}"/> to place created <see cref="WeightedSpanTerm"/>s in</param>
         /// <param name="spanQuery"><see cref="SpanQuery"/> to extract Terms from</param>
         /// <exception cref="IOException">If there is a low-level I/O error</exception>
         protected virtual void ExtractWeightedSpanTerms(IDictionary<string, WeightedSpanTerm> terms, SpanQuery spanQuery)
@@ -336,10 +336,10 @@ protected virtual void ExtractWeightedSpanTerms(IDictionary<string, WeightedSpan
         }
 
         /// <summary>
-        /// Fills a <see cref="T:IDictionary{string, WeightedSpanTerm}"/> with <see cref="WeightedSpanTerm"/>s using the terms from 
+        /// Fills a <see cref="T:IDictionary{string,WeightedSpanTerm}"/> with <see cref="WeightedSpanTerm"/>s using the terms from 
         /// the supplied <see cref="Search.Spans.SpanQuery"/>.
         /// </summary>
-        /// <param name="terms"><see cref="T:IDictionary{string, WeightedSpanTerm}"/> to place created <see cref="WeightedSpanTerm"/>s in</param>
+        /// <param name="terms"><see cref="T:IDictionary{string,WeightedSpanTerm}"/> to place created <see cref="WeightedSpanTerm"/>s in</param>
         /// <param name="query"><see cref="Query"/> to extract Terms from</param>
         /// <exception cref="IOException">If there is a low-level I/O error</exception>
         protected virtual void ExtractWeightedTerms(IDictionary<string, WeightedSpanTerm> terms, Query query)
@@ -448,7 +448,7 @@ public override IBits GetDocsWithField(string field)
         }
 
         /// <summary>
-        /// Creates an <see cref="T:IDictionary{string, WeightedSpanTerm}"/> from the given <see cref="Query"/> and <see cref="Analysis.TokenStream"/>.
+        /// Creates an <see cref="T:IDictionary{string,WeightedSpanTerm}"/> from the given <see cref="Query"/> and <see cref="Analysis.TokenStream"/>.
         /// </summary>
         /// <param name="query"><see cref="Query"/> that caused hit</param>
         /// <param name="tokenStream"><see cref="Analysis.TokenStream"/> of text to be highlighted</param>
@@ -461,7 +461,7 @@ public virtual IDictionary<string, WeightedSpanTerm> GetWeightedSpanTerms(Query
 
 
         /// <summary>
-        /// Creates an <see cref="T:IDictionary{string, WeightedSpanTerm}"/> from the given <see cref="Query"/> and <see cref="Analysis.TokenStream"/>.
+        /// Creates an <see cref="T:IDictionary{string,WeightedSpanTerm}"/> from the given <see cref="Query"/> and <see cref="Analysis.TokenStream"/>.
         /// </summary>
         /// <param name="query"><see cref="Query"/> that caused hit</param>
         /// <param name="tokenStream"><see cref="Analysis.TokenStream"/> of text to be highlighted</param>
@@ -495,7 +495,7 @@ public virtual IDictionary<string, WeightedSpanTerm> GetWeightedSpanTerms(Query
         }
 
         /// <summary>
-        /// Creates an <see cref="T:IDictionary{string, WeightedSpanTerm}"/> from the given <see cref="Query"/> and <see cref="Analysis.TokenStream"/>. Uses a supplied
+        /// Creates an <see cref="T:IDictionary{string,WeightedSpanTerm}"/> from the given <see cref="Query"/> and <see cref="Analysis.TokenStream"/>. Uses a supplied
         /// <see cref="IndexReader"/> to properly Weight terms (for gradient highlighting).
         /// </summary>
         /// <param name="query"><see cref="Query"/> that caused hit</param>

src/Lucene.Net.Highlighter/PostingsHighlight/PostingsHighlighter.cs

@@ -245,7 +245,7 @@ public virtual string[] Highlight(string field, Query query, IndexSearcher searc
         /// <param name="searcher">searcher that was previously used to execute the query.</param>
         /// <param name="topDocs">TopDocs containing the summary result documents to highlight.</param>
         /// <returns>
-        /// <see cref="T:IDictionary{string, string[]}"/> keyed on field name, containing the array of formatted snippets
+        /// <see cref="T:IDictionary{string,string[]}"/> keyed on field name, containing the array of formatted snippets
         /// corresponding to the documents in <paramref name="topDocs"/>.
         /// If no highlights were found for a document, the
         /// first sentence from the field will be returned.
@@ -278,7 +278,7 @@ public virtual IDictionary<string, string[]> HighlightFields(string[] fields, Qu
         /// <param name="topDocs">TopDocs containing the summary result documents to highlight.</param>
         /// <param name="maxPassages">The maximum number of top-N ranked passages per-field used to form the highlighted snippets.</param>
         /// <returns>
-        /// <see cref="T:IDictionary{string, string[]}"/> keyed on field name, containing the array of formatted snippets
+        /// <see cref="T:IDictionary{string,string[]}"/> keyed on field name, containing the array of formatted snippets
         /// corresponding to the documents in <paramref name="topDocs"/>.
         /// If no highlights were found for a document, the
         /// first <paramref name="maxPassages"/> sentences from the
@@ -308,7 +308,7 @@ public virtual IDictionary<string, string[]> HighlightFields(string[] fields, Qu
         /// <param name="docidsIn">containing the document IDs to highlight.</param>
         /// <param name="maxPassagesIn">The maximum number of top-N ranked passages per-field used to form the highlighted snippets.</param>
         /// <returns>
-        /// <see cref="F:IDictionary{string, string[]}"/> keyed on field name, containing the array of formatted snippets
+        /// <see cref="T:IDictionary{string,string[]}"/> keyed on field name, containing the array of formatted snippets
         /// corresponding to the documents in <paramref name="docidsIn"/>.
         /// If no highlights were found for a document, the
         /// first <c>maxPassages</c> from the field will
@@ -375,7 +375,7 @@ protected override int Compare(int i, int j)
         /// <param name="docidsIn">containing the document IDs to highlight.</param>
         /// <param name="maxPassagesIn">The maximum number of top-N ranked passages per-field used to form the highlighted snippets.</param>
         /// <returns>
-        /// <see cref="T:IDictionary{string, object[]}"/> keyed on field name, containing the array of formatted snippets
+        /// <see cref="T:IDictionary{string,object[]}"/> keyed on field name, containing the array of formatted snippets
         /// corresponding to the documents in <paramref name="docidsIn"/>.
         /// If no highlights were found for a document, the
         /// first <paramref name="maxPassagesIn"/> from the field will

src/Lucene.Net.Replicator/package.md

@@ -25,7 +25,7 @@ application should publish an [IndexAndTaxonomyRevision](xref:Lucene.Net.Replica
 When the replication client detects that there is a newer revision available, it copies the files of the revision and
 then invokes the handler to complete the operation (e.g. copy the files to the index directory, sync them, reopen an
 index reader etc.). By default, only files that do not exist in the handler's
-[current revision files](xref:Lucene.Net.Replicator.IReplicationHandler.html#Lucene_Net_Replicator_IReplicationHandler_CurrentRevisionFiles) are copied,
+[current revision files](xref:Lucene.Net.Replicator.IReplicationHandler#Lucene_Net_Replicator_IReplicationHandler_CurrentRevisionFiles) are copied,
 however this can be overridden by extending the client.
 
 <!-- Old Code Sample - not sure whether this is useful
@@ -83,16 +83,16 @@ public class AspNetCoreReplicationRequest : IReplicationRequest
     private readonly HttpRequest request;
 
     // Inject the actual request object in the constructor.
-    public AspNetCoreReplicationRequest(HttpRequest request) 
+    public AspNetCoreReplicationRequest(HttpRequest request)
         => this.request = request;
 
     // Provide the full path relative to the host.
     // In the common case in AspNetCore this should just return the full path, so PathBase + Path are concatenated and returned.
-    // 
+    //
     // The path expected by the ReplicatorService is {context}/{shard}/{action} where:
     //  - action may be Obtain, Release or Update
     //  - context is the same context that is provided to the ReplicatorService constructor and defaults to '/replicate'
-    public string Path 
+    public string Path
         => request.PathBase + request.Path;
 
     // Return values for parameters used by the ReplicatorService
@@ -103,7 +103,7 @@ public class AspNetCoreReplicationRequest : IReplicationRequest
     // - filename: The file name
     //
     // In this implementation a exception is thrown in the case that parameters are provided multiple times.
-    public string QueryParam(string name) 
+    public string QueryParam(string name)
         => request.Query[name].SingleOrDefault();
 }
 ```
@@ -118,7 +118,7 @@ This is also very straight forward.
 public class AspNetCoreReplicationResponse : IReplicationResponse
 {
     private readonly HttpResponse response;
-    
+
     // Inject the actual response object in the constructor.
     public AspNetCoreReplicationResponse(HttpResponse response)
         => this.response = response;
@@ -174,15 +174,15 @@ IndexWriter writer = new IndexWriter(FSDirectory.Open("..."), config);
 For the absolute minimal solution we can wire the <xref:Lucene.Net.Replicator.Http.ReplicationService> up on the server side as:
 
 ```cs
-LocalReplicator replicator = new LocalReplicator(); 
+LocalReplicator replicator = new LocalReplicator();
 ReplicatorService service = new ReplicationService(new Dictionary<string, IReplicator>{
     ["shard_name"] = replicator
 }, "/api/replicate");
 
 app.Map("/api/replicate", builder => {
     builder.Run(async context => {
         await Task.Yield();
-        service.Perform(context.Request, context.Response); 
+        service.Perform(context.Request, context.Response);
     });
 });
 ```
@@ -200,10 +200,10 @@ On the client side create a new <xref:Lucene.Net.Replicator.Http.HttpReplicator>
 ```cs
 IReplicator replicator = new HttpReplicator("http://{host}:{port}/api/replicate/shard_name");
 ReplicationClient client = new ReplicationClient(
-    replicator, 
+    replicator,
     new IndexReplicationHandler(
-        FSDirectory.Open(...directory...), 
-        () => ...onUpdate...), 
+        FSDirectory.Open(...directory...),
+        () => ...onUpdate...),
         new PerSessionDirectoryFactory(...temp-working-directory...));
 
 //Now either start the Update Thread or do manual pulls periodically.

src/Lucene.Net.Suggest/Suggest/Fst/FSTCompletionLookup.cs

@@ -289,7 +289,7 @@ public override IList<LookupResult> DoLookup(string key, IEnumerable<BytesRef> c
         }
 
         /// <summary>
-        /// Returns the bucket (weight) as a <see cref="T:long?"/> for the provided key if it exists,
+        /// Returns the bucket (weight) as a <see cref="T:Nullable{long}"/> for the provided key if it exists,
         /// otherwise null if it does not.
         /// </summary>
         public virtual long? Get(string key)