Skip to content

docs(config): mark the group headings and describe the 24 undocumented properties - #3434

Merged
marevol merged 2 commits into
mainfrom
docs/normalise-config-property-headings
Sep 10, 2026
Merged

docs(config): mark the group headings and describe the 24 undocumented properties#3434
marevol merged 2 commits into
mainfrom
docs/normalise-config-property-headings

Conversation

@marevol

@marevol marevol commented Sep 10, 2026

Copy link
Copy Markdown
Contributor

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.rst lists every configuration property with its
description 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.tile even acquired an invented description, "The domain name
of 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.repositories value.
#> is a marker commented-out configuration never starts with. The terse lowercase
labels also become display titles, since they turn into the documentation's section
headings: # job to #> Job, # html to #> Crawler HTML, # acl to #> 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.format accepts only
html and json and fails the job on anything else, that the per-user login bucket is
keyed 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:

key what happens
theme.allowed.archive.extensions getThemeAllowedArchiveExtensions() has no caller. AdminThemeAction.hasZipExtension hardcodes endsWith(".zip").
theme.assets.cache.max.age getThemeAssetsCacheMaxAgeAsInteger() has no caller. StaticThemeResponder sends a literal max-age=86400 — which equals the default, so changing the key looks harmless and does nothing.
theme.assets.precompressed isThemeAssetsPrecompressed() has no caller, and no precompressed asset path exists; the responder sets Vary: Accept-Encoding but negotiates nothing.
rag.chat.message.max.length Read through FessProp#getSystemProperty, which consults conf/system.properties then -Dfess.<key> then a literal "4000". It never reads fess_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 is
    a comment.
  • Parsing the file with the new fess-docs generator yields 4 sections, 26 groups and
    639 keys, none without a description (before: 24 without).
  • The two commented-out examples that the old heuristic misread are still commented-out
    configuration and are no longer mistaken for headings.

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.
@marevol
marevol added this pull request to stack #3436 September 10, 2026 22:52
@marevol marevol self-assigned this Sep 10, 2026
@marevol marevol added the task label Sep 10, 2026
@marevol marevol added this to the 15.9.0 milestone Sep 10, 2026
@marevol
marevol merged commit 00d6901 into main Sep 10, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant