apache / apache/lucene

Improve analyzer factoryies' Javadoc. [LUCENE-8873]

Open
#9,916 2 comments 0 reactions 0 assignees View on GitHub
legacy-jira-priority:Minor module:analysis type:enhancement
Dominant language
Java
Stars
3.6k
Forks
1.4k
Avg merge
2d 11h
Merged PRs (30d)
88

Description

Currently, the documentation for analyzer factories (subclasses of `TokenizerFactory`, `CharFilterFactory`, `TokenFilterFactory`) still includes lots of Solr schema.xml examples and not all properties are documented. From my perspective, the latter is more problematic because users who want to use the factories have to refer to source code to know what properties are defined.

To improve documentation, XML examples should be removed for cleanup, and instead, **all properties which can be passed to factory constructors should be properly documented**.

Documentation is often overlooked so some validation rules and standardization effort would be desired (e.g. marking properties by annotations).

---
Migrated from [LUCENE-8873](https://issues.apache.org/jira/browse/LUCENE-8873) by Tomoko Uchida (@mocobeta), updated Aug 12 2019
Linked issues:
- #9612

Contributor guide

Open the contributing guide

Research direction

Start by locating the analyzer factory subclasses of TokenizerFactory, CharFilterFactory, and TokenFilterFactory, then review how their constructor properties are currently documented. Check the existing Javadocs and Solr schema.xml examples first. Done means removing the XML examples and documenting every constructor property, with any validation or annotation standardization agreed for the affected factories.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.