docs(config): mark the group headings and describe the 24 undocumented properties - #3434
Merged
Merged
Conversation
The file already groups its properties: a bare comment followed by a blank line introduces a run of related keys, and 23 of them do. The convention cannot be read reliably, though, because a commented-out configuration example has exactly the same shape. Two are picked up as headings by that rule today: a continuation line of the commented-out remote-debug JVM options, and a commented-out plugin.repositories value. Give the headings a marker of their own, `#> `, which commented-out configuration never starts with, and a display title in place of the terse lowercase labels, since fess-docs is about to generate the configuration reference page from this file and these become its section headings. Comments only. No key, default or ordering changes.
Every other key in fess_config.properties carries a sentence saying what it does; these 24 were added without one. Each description here was written from the code that reads the key, not from the key's name, and records what the value actually controls -- that a rate limit of 0 or less disables the gate, that the export format accepts only html and json, that the per-user login bucket is keyed by client IP and user name rather than by user alone. Four of them document a value that has no effect, which is worth stating where an operator will read it rather than leaving them to find out: - theme.allowed.archive.extensions, theme.assets.cache.max.age and theme.assets.precompressed have a generated FessConfig accessor but no caller anywhere in src/main/java. The upload action hardcodes .zip, the static theme responder hardcodes max-age=86400, and there is no precompressed asset path at all. - rag.chat.message.max.length is read through FessProp#getSystemProperty, which consults conf/system.properties and then -Dfess.<key>, and never fess_config.properties. The value here is documentation; editing it changes nothing. Comments only. No key, default or ordering changes.
This was referenced Sep 10, 2026
marevol
added this pull request to stack #3436
September 10, 2026 22:52
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.
Groundwork for codelibs/fess-docs, which is about to generate its configuration
reference page from this file instead of maintaining it by hand. Comments only — no key,
default or ordering changes.
Why the page is being generated
en/<version>/config/properties.rstlists every configuration property with itsdescription and default. Kept by hand it rotted: measured against this file it is 120
keys short, and it documents 10 keys that no longer exist, several under a
misspelling —
app.cipher.algorism,app.digest.algorism,domain.tile,http.proxy.Host.domain.tileeven acquired an invented description, "The domain nameof the tile server". It also carried jcifs property names no supported jcifs version
reads, until codelibs/fess-docs#532.
Generating it makes this file the single source for the keys, the defaults, the
descriptions, the headings and the order.
What changes here
Group headings get a marker. The file already groups its properties: a bare comment
followed by a blank line introduces a run of related keys, and 23 do. That convention
cannot be read reliably, because a commented-out configuration example has exactly the
same shape — two are picked up as headings by that rule today, a continuation line of the
commented-out remote-debug JVM options and a commented-out
plugin.repositoriesvalue.#>is a marker commented-out configuration never starts with. The terse lowercaselabels also become display titles, since they turn into the documentation's section
headings:
# jobto#> Job,# htmlto#> Crawler HTML,# aclto#> ACL.The four top-level DBFlute banners — Core, Rate Limiting, Index, Web — are read as they
are and are untouched.
The 24 keys with no comment get one. Each was written from the code that reads the
key rather than from the key's name, so it records what the value actually controls: that
a login rate limit of 0 or less disables the gate, that
index.export.formataccepts onlyhtmlandjsonand fails the job on anything else, that the per-user login bucket iskeyed by client IP and user name rather than by user alone.
Four of those keys turned out to have no effect
Worth stating where an operator will read it, rather than leaving them to discover it:
theme.allowed.archive.extensionsgetThemeAllowedArchiveExtensions()has no caller.AdminThemeAction.hasZipExtensionhardcodesendsWith(".zip").theme.assets.cache.max.agegetThemeAssetsCacheMaxAgeAsInteger()has no caller.StaticThemeRespondersends a literalmax-age=86400— which equals the default, so changing the key looks harmless and does nothing.theme.assets.precompressedisThemeAssetsPrecompressed()has no caller, and no precompressed asset path exists; the responder setsVary: Accept-Encodingbut negotiates nothing.rag.chat.message.max.lengthFessProp#getSystemProperty, which consultsconf/system.propertiesthen-Dfess.<key>then a literal"4000". It never readsfess_config.properties, so the value here is documentation only.Each is described as what it is for, followed by the caveat. Wiring them up or removing
them is a separate call — this PR only stops the file from claiming they work.
Verification
git diff -U0 | grep -cE '^[-+][^-+#]'is 0 across both commits: every changed line isa comment.
639 keys, none without a description (before: 24 without).
configuration and are no longer mistaken for headings.