apache / apache/lucenenet

Remaining Documentation Bugs

Open
#969 0 comments 0 reactions 0 assignees View on GitHub
docs good-first-issue help-wanted is:bug up-for-grabs
Dominant language
C#
Stars
2.4k
Forks
658
Avg merge
3d 5h
Merged PRs (30d)
9

Description

### Is there an existing issue for this?

- [X] I have searched the existing issues

### Describe the bug

After #911, it was discovered during testing that several documentation bugs remain. This item tracks those issues:

1. The Performance Notes section here is not formatted correctly: /api/memory/Lucene.Net.Index.Memory.html#example-xquery-usage
2. The "where" section formulas are not being formatted correctly on /api/core/Lucene.Net.Search.Similarities.TFIDFSimilarity.html. Do note that the formulas also look differently than they did in the [Javadoc](https://lucene.apache.org/core/4_8_0/core/org/apache/lucene/search/similarities/TFIDFSimilarity.html) (it was also this way in prior releases). Ideally, we could find a way to make the formulas look right both in the API docs and Intellisense.
3. In this block: http://localhost:8080/api/core/Lucene.Net.Analysis.html#attribute-and-attributesource, the table is missing the entire first column with the attributes and links. This seems like important info that is missing. It looks like several other tables are failing to resolve links, but this one is stripping them completely.
4. It is difficult to remember where you have been on the API docs if the link visited text is the same as the unvisited text, which was a bit annoying when trying to visit all of the links for a test.
5. Several unconverted xrefs on /api/analysis-opennlp/Lucene.Net.Analysis.OpenNlp.html without warnings during build

### Expected Behavior

_No response_

### Steps To Reproduce

_No response_

### Exceptions (if any)

_No response_

### Lucene.NET Version

_No response_

### .NET Version

_No response_

### Operating System

_No response_

### Anything else?

_No response_

Contributor guide

Open the contributing guide

Research direction

Start by inspecting the affected generated API pages: Memory.html, TFIDFSimilarity.html, Analysis.html, and Analysis.OpenNlp.html, then compare the formula rendering with the linked Javadoc and review the documentation build output. Done means the listed formatting, links, visited-link styling, and unconverted xrefs are corrected without build warnings.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.