Situation

The documentation about SecHub config values is a little bit messy and attributes are often not easy to find.

Wrong and duplicated scopes

In our SecHub documentation (techdoc, operations) we have

• general config
• scheduler definitions

where the SecHub server config values and their defaults are described.

By a "scope" in the documentation we can group some values together.

Unfortunately the scopes are not a mandatory attribute inside the java annotations, and when missing, the name of the scope is automatically generated and is often wrong.

Examples:
scheduler, schedule, s ... for same type of configurations

No headlines for scopes

Inside the headline of asciidoc output, we have only

• general config
• scheduler definitions

But there are some many settings, that it is very cumbersome to find them inside the document

Scheduler definitions is a misleading name

"Scheduler definition" was chosen as a name because it describes configurations for the @Schedule annotation from Spring Boot. But this is misleading because in SecHub we talk about Scheduler when it comes to job processing...

Scheduler definition has duplicated entries for auto cleanup

For every domain own scope is defined, so the same setup (they have the same key) appears multiple
times! This is confusing

Wanted

The upper mentioned problems shall be fixed

Solution

Wrong and duplicated scopes

• Introduce constants for groups (scopes)
• Change annotation for @MustBeDocumented and make scope mandatory without any default
• Remove the scope auto value generation inside asciidoc generator
• Set all scopes in parts annotated with @MustBeDocumented by the introduced constant

No headlines for scopes

• Change asciidoc generator: Every table for a given scope shall have also a headline of level 4, means listed in TOC and easier to find

Rename "Scheduler definitions"

• Rename to "Trigger setup"

Duplicated "autocleanup" entries

• Use "auto cleanup" as scope for all domains -> the setting shall only be generated once