Fix documentation xref links and most docfx build warnings, #969 - #1439
Open
paulirwin wants to merge 2 commits into
Open
Fix documentation xref links and most docfx build warnings, #969#1439paulirwin wants to merge 2 commits into
paulirwin wants to merge 2 commits into
Conversation
Reduces docfx build warnings from 645 to 24 (-96%) and resolves all
UidNotFound cross-reference failures.
Doc comment fixes:
- Retarget <see cref> that pointed at private/internal members to the
public property where one exists (LiveIndexWriterConfig.MergePolicy,
NumericRangeQuery.PrecisionStep, Int64BitSet.Length, MaxCodeLen,
MaxThreadCount), or <c> where no public equivalent exists. docfx does
not emit pages for non-public members, so these anchors never resolved.
- Correct stale ports: IndexOptions was de-nested from FieldInfo, Judge
and QualityQueryParser became IJudge/IQualityQueryParser, and several
.NET signatures take an extra CancellationToken.
- Replace leftover javadoc syntax ({@docroot}, package-summary.html,
../core/*.html) with xref uids or plain code formatting.
- Fix heading slugs and anchors that no longer matched generated ids,
including a TOC that had been "fixed" by pasting in garbled slugs.
- Formulas in NumericRangeQuery referenced doc-files/*.png that were
never ported; render them as text and keep the LaTeX in a comment.
Build configuration:
- Add missing xrefmaps so cross-project uids resolve (core, icu, join,
memory, site).
- Add icu and memory to the intentional duplicates in docs.ps1; both
have circular xrefmap dependencies, matching the existing codecs/core
workaround.
Known remaining: 24 warnings and 8 dead xref: links on 5 pages. These
are cross-project uids in overwrite-only files, which no xref syntax
resolves, plus 3 benign DuplicateUids where docfx merges correctly and
an intentional OpenNLP security pin. Upstream docfx PR #11090 addresses
the underlying cause: uids carry no assembly component, so assemblies
sharing a namespace collapse onto one identity.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
paulirwin
requested review from
NightOwl888
and
a balanced review from Copilot
August 10, 2026 17:14
paulirwin
added
the
notes:website-or-documentation
Contributor
There was a problem hiding this comment.
Pull request overview
Repairs DocFX cross-references, anchors, and stale Java documentation while reducing documentation build warnings.
Changes:
- Adds missing cross-project xref maps and rebuild passes.
- Corrects stale API/member links and signatures.
- Repairs headings, formulas, and conceptual documentation links.
Reviewed changes
Copilot reviewed 83 out of 83 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
websites/apidocs/index.md |
Updates module links. |
websites/apidocs/docs.ps1 |
Adds repeat DocFX build passes. |
websites/apidocs/docfx.site.json |
Adds TestFramework xrefs. |
websites/apidocs/docfx.memory.json |
Adds QueryParser xrefs. |
websites/apidocs/docfx.join.json |
Adds Grouping xrefs. |
websites/apidocs/docfx.icu.json |
Adds Highlighter xrefs. |
websites/apidocs/docfx.core.json |
Adds cross-project xref maps. |
websites/apidocs/apiSpec/core/Lucene_Net_Codecs.md |
Repairs codec documentation links. |
src/Lucene.Net/Util/PriorityQueue.cs |
Removes invalid field crefs. |
src/Lucene.Net/Util/Packed/EliasFanoEncoder.cs |
Removes invalid field crefs. |
src/Lucene.Net/Util/MergedIterator.cs |
Corrects parameter formatting. |
src/Lucene.Net/Util/LongBitSet.cs |
Links the public length property. |
src/Lucene.Net/Util/Fst/package.md |
Corrects generic and method xrefs. |
src/Lucene.Net/Util/BroadWord.cs |
Removes an inaccessible method xref. |
src/Lucene.Net/Support/Codecs/DefaultPostingsFormatFactory.cs |
Corrects private-field references. |
src/Lucene.Net/Support/Codecs/DefaultDocValuesFormatFactory.cs |
Corrects private-field references. |
src/Lucene.Net/Support/Codecs/DefaultCodecFactory.cs |
Corrects private-field references. |
src/Lucene.Net/Store/RAMDirectory.cs |
Corrects constant formatting. |
src/Lucene.Net/Search/TopFieldCollector.cs |
Corrects private-field formatting. |
src/Lucene.Net/Search/Similarities/TFIDFSimilarity.cs |
Replaces stale Javadoc link. |
src/Lucene.Net/Search/Similarities/package.md |
Uses a module xref. |
src/Lucene.Net/Search/Query.cs |
Replaces stale module link. |
src/Lucene.Net/Search/PhraseQuery.cs |
Corrects private collection references. |
src/Lucene.Net/Search/package.md |
Repairs API links and anchors. |
src/Lucene.Net/Search/NumericRangeQuery.cs |
Repairs property links, headings, and formulas. |
src/Lucene.Net/Search/MultiPhraseQuery.cs |
Corrects private collection references. |
src/Lucene.Net/Search/FuzzyQuery.cs |
Replaces stale Suggest link. |
src/Lucene.Net/Search/BitsFilteredDocIdSet.cs |
Corrects parameter formatting. |
src/Lucene.Net/overview.md |
Converts module and demo links to xrefs. |
src/Lucene.Net/Index/SegmentInfos.cs |
Corrects private-field references. |
src/Lucene.Net/Index/package.md |
Repairs anchors and API UIDs. |
src/Lucene.Net/Index/LiveIndexWriterConfig.cs |
Removes invalid private-member cref. |
src/Lucene.Net/Index/IndexWriter.cs |
Links public configuration properties. |
src/Lucene.Net/Index/DocTermOrds.cs |
Corrects internal constant formatting. |
src/Lucene.Net/Index/ConcurrentMergeScheduler.cs |
Links the public property. |
src/Lucene.Net/Document/LongField.cs |
Removes a brittle fragment link. |
src/Lucene.Net/Document/IntField.cs |
Removes a brittle fragment link. |
src/Lucene.Net/Document/FloatField.cs |
Removes a brittle fragment link. |
src/Lucene.Net/Document/DoubleField.cs |
Removes a brittle fragment link. |
src/Lucene.Net/Codecs/package.md |
Replaces stale Javadoc module link. |
src/Lucene.Net/Codecs/MultiLevelSkipListWriter.cs |
Corrects parameter formatting. |
src/Lucene.Net/Codecs/MultiLevelSkipListReader.cs |
Corrects parameter formatting. |
src/Lucene.Net/Codecs/Compressing/CompressingStoredFieldsFormat.cs |
Corrects parameter formatting. |
src/Lucene.Net/Codecs/BlockTreeTermsWriter.cs |
Corrects private-field formatting. |
src/Lucene.Net/Analysis/package.md |
Repairs TestFramework and disposal references. |
src/Lucene.Net/Analysis/NumericTokenStream.cs |
Links the public property. |
src/Lucene.Net.TestFramework/Codecs/Lucene40/Lucene40PostingsWriter.cs |
Corrects constant formatting. |
src/Lucene.Net.Suggest/Suggest/FileDictionary.cs |
Corrects delimiter formatting. |
src/Lucene.Net.Suggest/Suggest/Analyzing/FuzzySuggester.cs |
Corrects parameter formatting. |
src/Lucene.Net.Suggest/Suggest/Analyzing/AnalyzingSuggester.cs |
Corrects parameter formatting. |
src/Lucene.Net.Replicator/IndexAndTaxonomyRevision.cs |
Updates version documentation. |
src/Lucene.Net.QueryParser/overview.md |
Repairs generated heading anchors. |
src/Lucene.Net.QueryParser/Flexible/Core/package.md |
Corrects generic interface xref. |
src/Lucene.Net.QueryParser/Classic/QueryParser.cs |
Replaces stale syntax link. |
src/Lucene.Net.QueryParser/Classic/package.md |
Repairs operator anchors. |
src/Lucene.Net.Queries/Function/ValueSources/IfFunction.cs |
Corrects private-field formatting. |
src/Lucene.Net.Memory/MemoryIndex.cs |
Replaces stale query syntax link. |
src/Lucene.Net.Join/package.md |
Corrects interface and signature xrefs. |
src/Lucene.Net.Highlighter/Highlight/WeightedSpanTermExtractor.cs |
Corrects private-field formatting. |
src/Lucene.Net.Facet/Taxonomy/WriterCache/CompactLabelToOrdinal.cs |
Corrects constructor parameter formatting. |
src/Lucene.Net.Facet/package.md |
Updates the cancellation-token signature. |
src/Lucene.Net.Demo/overview.md |
Repairs module and query syntax links. |
src/Lucene.Net.Benchmark/Quality/package.md |
Replaces stale Java links and names. |
src/Lucene.Net.Benchmark/ByTask/Tasks/AddIndexesTask.cs |
Corrects parameter formatting. |
src/Lucene.Net.Benchmark/ByTask/package.md |
Repairs generated heading anchors. |
src/Lucene.Net.Analysis.Phonetic/Language/Soundex.cs |
Replaces inaccessible member references. |
src/Lucene.Net.Analysis.Phonetic/Language/Metaphone.cs |
Updates property references. |
src/Lucene.Net.Analysis.Phonetic/Language/DoubleMetaphone.cs |
Updates property reference. |
src/Lucene.Net.Analysis.ICU/overview.md |
Repairs a heading anchor. |
src/Lucene.Net.Analysis.ICU/Collation/ICUCollationKeyAnalyzer.cs |
Removes a dead fragment link. |
src/Lucene.Net.Analysis.Common/Collation/package.md |
Replaces internal API links with public guidance. |
src/Lucene.Net.Analysis.Common/Analysis/Util/FilteringTokenFilter.cs |
Removes a dead fragment link. |
src/Lucene.Net.Analysis.Common/Analysis/Util/CharArrayMap.cs |
Removes invalid method and fragment links. |
src/Lucene.Net.Analysis.Common/Analysis/Util/BufferedCharFilter.cs |
Corrects parameter formatting. |
src/Lucene.Net.Analysis.Common/Analysis/Reverse/ReverseStringFilter.cs |
Corrects parameter formatting. |
src/Lucene.Net.Analysis.Common/Analysis/Pattern/PatternCaptureGroupTokenFilter.cs |
Corrects parameter formatting. |
src/Lucene.Net.Analysis.Common/Analysis/Miscellaneous/StemmerOverrideFilter.cs |
Corrects parameter formatting. |
src/Lucene.Net.Analysis.Common/Analysis/Miscellaneous/LimitTokenPositionFilterFactory.cs |
Updates configuration-key documentation. |
src/Lucene.Net.Analysis.Common/Analysis/Miscellaneous/LimitTokenCountFilterFactory.cs |
Updates configuration-key documentation. |
src/Lucene.Net.Analysis.Common/Analysis/Core/TypeTokenFilter.cs |
Corrects parameter formatting. |
src/Lucene.Net.Analysis.Common/Analysis/Compound/HyphenationCompoundWordTokenFilter.cs |
Replaces stale HTML links. |
src/Lucene.Net.Analysis.Common/Analysis/Compound/DictionaryCompoundWordTokenFilter.cs |
Replaces stale HTML links. |
src/dotnet/Lucene.Net.ICU/overview.md |
Converts the Highlighter link to an xref. |
Suppressed comments (1)
src/Lucene.Net.QueryParser/overview.md:54
- The appended cross-reference starts immediately after the example without sentence punctuation. Separate the example from the new “See” sentence and use standard
e.g.punctuation.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| /// <para/> | ||
| /// This class is thread-safe. | ||
| /// Although not strictly immutable, the <see cref="maxLength"/> field is not actually used. | ||
| /// Although not strictly immutable, the <see cref="MaxLength"/> field is not actually used. |
| /// <para/> | ||
| /// This class is conditionally thread-safe. | ||
| /// The instance field <see cref="maxCodeLen"/> is mutable <see cref="MaxCodeLen"/> | ||
| /// The instance field <see cref="MaxCodeLen"/> is mutable <see cref="MaxCodeLen"/> |
Comment on lines
+30
to
31
| /// This class is conditionally thread-safe. The instance field <see cref="MaxCodeLen"/> is mutable | ||
| /// <see cref="MaxCodeLen"/> but is not volatile, and accesses are not synchronized. If an instance of the class is |
|
|
||
| /// <summary> | ||
| /// Compares this <see cref="IndexAndTaxonomyRevision"/> to the given <see cref="version"/>. | ||
| /// Compares this <see cref="IndexAndTaxonomyRevision"/> to the given <see cref="Version"/>. |
| /// </fieldType></code> | ||
| /// <para> | ||
| /// The <see cref="consumeAllTokens"/> property is optional and defaults to <c>false</c>. | ||
| /// The <see cref="CONSUME_ALL_TOKENS_KEY"/> property is optional and defaults to <c>false</c>. |
| /// </fieldType></code> | ||
| /// <para> | ||
| /// The <see cref="consumeAllTokens"/> property is optional and defaults to <c>false</c>. | ||
| /// The <see cref="CONSUME_ALL_TOKENS_KEY"/> property is optional and defaults to <c>false</c>. |
| ## Changing Scoring — Similarity | ||
|
|
||
| Changing [Similarity](xref:Lucene.Net.Search.Similarities.Similarity) is an easy way to influence scoring, this is done at index-time with [IndexWriterConfig.setSimilarity](xref:Lucene.Net.Index.IndexWriterConfig#methods) and at query-time with [IndexSearcher.Similarity](xref:Lucene.Net.Search.IndexSearcher#Lucene_Net_Index_IndexWriterConfig_Similarity). Be sure to use the same Similarity at query-time as at index-time (so that norms are encoded/decoded correctly); Lucene makes no effort to verify this. | ||
| Changing [Similarity](xref:Lucene.Net.Search.Similarities.Similarity) is an easy way to influence scoring, this is done at index-time with [IndexWriterConfig.setSimilarity](xref:Lucene.Net.Index.IndexWriterConfig#methods) and at query-time with [IndexSearcher.Similarity](xref:Lucene.Net.Search.IndexSearcher#Lucene_Net_Search_IndexSearcher_Similarity). Be sure to use the same Similarity at query-time as at index-time (so that norms are encoded/decoded correctly); Lucene makes no effort to verify this. |
| ## Analyzing | ||
|
|
||
| QueryParser that passes Fuzzy-, Prefix-, Range-, and WildcardQuerys through the given analyzer. | ||
| QueryParser that passes Fuzzy-, Prefix-, Range-, and WildcardQuerys through the given analyzer. See <xref:Lucene.Net.QueryParsers.Analyzing>. |
| ### Testing Your Analysis Component | ||
|
|
||
| The Lucene.Net.TestFramework component defines [BaseTokenStreamTestCase](../test-framework/Lucene.Net.Analysis.BaseTokenStreamTestCase.html). By extending this class, you can create NUnit tests that validate that your Analyzer and/or analysis components correctly implement the protocol. The CheckRandomData()methods of that class are particularly effective in flushing out errors. | ||
| The Lucene.Net.TestFramework component defines [BaseTokenStreamTestCase](xref:Lucene.Net.Analysis.BaseTokenStreamTestCase). By extending this class, you can create NUnit tests that validate that your Analyzer and/or analysis components correctly implement the protocol. The CheckRandomData()methods of that class are particularly effective in flushing out errors. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fix documentation xref links and most docfx build warnings
Related #969
Description
Reduces docfx build warnings from 645 to 24 (-96%) and resolves all
UidNotFoundcross-reference failures. Most of these were porting artifacts: Java's{@link #field}was mechanically converted to<see cref="field"/>, but where C# made those fields private, docfx emits no page and the anchor silently dangles.IndexWriter.mergePolicy/mergeScheduleralone accounted for 281 warnings, since one inherited doc comment is re-reported on every page that inherits it. These now point at the public property a reader can actually use (LiveIndexWriterConfig.MergePolicy), or fall back to<c>where no public equivalent exists. Also fixed: stale ports (IndexOptionswas de-nested fromFieldInfo;Judge/QualityQueryParserbecameIJudge/IQualityQueryParser; several .NET signatures take an extraCancellationToken), leftover javadoc syntax ({@docRoot},package-summary.html), heading anchors that no longer matched generated slugs, and missing xrefmap entries so cross-project links resolve. Every changed anchor was verified against the generated HTML: 104 xref+fragment links confirmed to resolve to an anchor on the page the uid actually points at.Known remaining: 23 warnings and 8 dead
xref:links across 5 pages. These are cross-project uids in overwrite-only files, which no xref syntax resolves; plus 3 benign DuplicateUids where docfx merges the pages correctly. Worth noting that docfx reports no warning for these dead links: it emitshref="xref:..."straight into the shipped HTML, so warning count alone is not a reliable signal here;grep -r 'href="xref:' _siteis. The underlying cause is that docfx uids carry no assembly component, so assemblies sharing a namespace collapse onto one identity (dotnet/docfx#11090 is one possible fix we're tracking).AI: analyzed and changes written by Claude Code, Opus 5, under my direction and review.