[JIRA] (HSEARCH-4667) Add a configuration properties reference to the reference documentation
by Yoann Rodière (JIRA)
Yoann Rodière ( https://hibernate.atlassian.net/secure/ViewProfile.jspa?accountId=557058%... ) *created* an issue
Hibernate Search ( https://hibernate.atlassian.net/browse/HSEARCH?atlOrigin=eyJpIjoiMDZhNTRk... ) / Task ( https://hibernate.atlassian.net/browse/HSEARCH-4667?atlOrigin=eyJpIjoiMDZ... ) HSEARCH-4667 ( https://hibernate.atlassian.net/browse/HSEARCH-4667?atlOrigin=eyJpIjoiMDZ... ) Add a configuration properties reference to the reference documentation ( https://hibernate.atlassian.net/browse/HSEARCH-4667?atlOrigin=eyJpIjoiMDZ... )
Issue Type: Task Assignee: Unassigned Components: documentation Created: 09/Aug/2022 06:12 AM Fix Versions: 6.x-backlog Priority: Major Reporter: Yoann Rodière ( https://hibernate.atlassian.net/secure/ViewProfile.jspa?accountId=557058%... )
We do document all configuration properties in the reference documentation already, but they’re spread all over the documentation.
It’s sometimes useful to simply have an index, a list of configuration properties with a short explanation; it seems it would have helped this user ( https://stackoverflow.com/q/73016660/6692043 ) , at least.
Javadoc is supposed to serve this purpose, especially since we have *Settings classes listing all configuration properties. However, there many *Settings classes spread over all modules, which makes it hard to quickly get a view of all possible configuration properties.
We should probably work on a tool that inspects source code or .class files, then generates a list of all configuration properties, with:
* The full property key, which is a prefix followed by the value of a Java constant in a *Settings class. Generating all possible prefixes might be a bit complex, especially for backend/index properties (see https://docs.jboss.org/hibernate/stable/search/reference/en-US/html_singl... ( https://docs.jboss.org/hibernate/stable/search/reference/en-US/html_singl... ) )
* The description of the property, which is the javadoc on the Java constant in a *Settings class.
* If possible, the default value of the property, which is the value of a Java constant with the same name as the one holding the property key, but in the *Settings.Defaults class. There is not always a default value.
Which tool to use for generating this configuration property reference? That’s an open question. Ideally it should offer great customization (to build the property keys) and also support extracting formatted javadoc. An ad-hoc tool based on some source/bytecode processing tool (annotation processor, …) might work, but the simpler the better, and we definitely don’t want to parse/render javadoc ourselves, so we’ll need an external tool for that, at least.
( https://hibernate.atlassian.net/browse/HSEARCH-4667#add-comment?atlOrigin... ) Add Comment ( https://hibernate.atlassian.net/browse/HSEARCH-4667#add-comment?atlOrigin... )
Get Jira notifications on your phone! Download the Jira Cloud app for Android ( https://play.google.com/store/apps/details?id=com.atlassian.android.jira.... ) or iOS ( https://itunes.apple.com/app/apple-store/id1006972087?pt=696495&ct=EmailN... ) This message was sent by Atlassian Jira (v1001.0.0-SNAPSHOT#100204- sha1:86bebeb )
2 years, 4 months