java - How to document .properties files?

Question

Is there a standard way of documenting .properties files? Something in the spirit of Javadoc where I have properties and documentation in the same file and can leverage IDE integration?

It might sound trivial but to illustrate my problem, consider the following example: Let's say I have a Java application which is controlled by a central .properties file in the format

key1=value1
key2=value2

To document the meaning of property keys I could use comments like this:

# key1 does this and that
key1=value1

But what if I have settings that are applied more than once?

# key1 causes component1 to behave so and so
component1.key1=value1

# key1 causes component2 to behave so and so
component2.key1=value2

In the above, the meaning of key1 is the same in both properties. However, I don't want to repeat the comment because I might have hundreds of components to which the key1 property is applied. I could use a single comment at the beginning like this:

# key1 causes the affected component to behave so and so
component1.key1=value1
component2.key1=value2
....

But then if I add a new component at the end, I would have to scroll up every time to find the associated documentation comment.

I'm looking for a way to define the meaning of the property pattern

[COMPONENT].key1=value1

in a way that I can easily refer to that documentation in an IDE - just like you do with Java code and Javadoc.

Answer 1

If your config is that complex I would consider using Typesafe config https://github.com/typesafehub/config/blob/master/README.md

Doing so would allow you to structure your config to remove duplication by using json or hcon.

Having done that, whatever loads the config should validate it and report any issues. If successful, build an obect representation of this complex config. Javabean in Java, case classes in Scala.

Document the code that loads the config and the code representing the config.

I've used this approach in Scala projects and it's saved a lot pain and confusion.