From e5d77c5f21ae37da6313d5bf4a02fbcc2786e87a Mon Sep 17 00:00:00 2001 From: A248 Date: Fri, 5 Feb 2021 22:19:23 -0500 Subject: [PATCH] Update Annotations.md with the latest information --- docs/Annotations.md | 32 +++++++++++++++++++++++++++++--- 1 file changed, 29 insertions(+), 3 deletions(-) diff --git a/docs/Annotations.md b/docs/Annotations.md index 25347f3..fe65c5c 100644 --- a/docs/Annotations.md +++ b/docs/Annotations.md @@ -15,16 +15,42 @@ Overrides the key of the configuration entry. If unspecified, the key is the met @DefaultBooleans, @DefaultIntegers, @DefaultLongs, @DefaultDoubles, and @DefaultStrings all specify a collection of elements of the noted type. +Since version 1.2.0, @DefaultObject is used to specify arbitrary default objects, and is usually appropriate for returning custom types which cannot be easily expressed as a String. If you can write your object as a single String value, you can use @DefaultString. @DefaultObject points to a name of a static method returning the default object; if the static method is in another class, it must be referred to by its qualified name, e.g. 'com.mypackage.MyConfigDefaults.staticMethodReturningDefaultObject'. + ### @ConfComments and @ConfHeader -@ConfComments adds comments to a configuration entry. @ConfHeader is placed on a configuration interface and sets the comment header of the entire configuration. +@ConfComments adds comments to a configuration entry. + +@ConfHeader adds a comment header to a configuration interface. -These annotations do not guarantee comments will be written to the underlying configuration format. JSON has no concept of a comment. YAML has comments but SnakeYAML does not write them. In these cases, DazzleConf has format-specific options, which are disabled by default, to hack comments into the configuration format. +These annotations do not guarantee comments will be written to the underlying configuration format. JSON has no concept of a comment. YAML has comments but SnakeYAML does not write them ([yet!](https://github.com/A248/DazzleConf/issues/10)). In these cases, DazzleConf has format-specific options, which are disabled by default, to hack comments into the configuration format. Consider using Hocon [once support is added for it](https://github.com/A248/DazzleConf/pull/6) - Hocon fully supports comments. ### @SubSection This annotation is required for nested configuration interfaces. Without it, DazzleConf cannot tell whether the object is supposed to be its own type, contained in a single key and value, or a nested config section. +Since version 1.2.0, @SubSection can also be used for map keys and collection elements + +Here is example usage of both applications: + +```java +public interface MyConfig { + + @SubSection + MySection mySubSection(); + + interface MySection { + } + + @DefaultObject("defaultExtraSections") + Map extraSections(); + + static Map defaultExtraSections(MySection defaultMySection /* optional parameter, see @DefaultObject javadoc */) { + return Map.of("key", defaultMySection); + } +} +``` + ## Other Annotations ### @ConfSerialisers and @ConfValidator @@ -33,7 +59,7 @@ Both these annotations take a class or classes as an argument. DazzleConf will i *ConfSerialiser* is placed on a configuration interface and specifies classes implementing *ValueSerialiser*. ValueSerialiser is to be used for implementing custom types; it is concerned with deserialisation and serialisation. URLValueSerialiser is one usable implementation serving as a good example. All the ValueSerialisers instantiated by *ConfSerialiser* will apply to the configuration entries in that configuration interface which the annotation is placed on. Note that nested config sections do not "inherit" this annotation. -*ConfValidator* is placed on a configuration entry and specifies a single class implementing *ValueValidator* applying to the entry. *ValueValidator* is designed to validate a value once it has been deserialised. +*ConfValidator* is placed on a configuration entry and specifies a single class implementing *ValueValidator* applying to the entry. *ValueValidator* is designed to validate a value once it has been deserialised. Usually, you want to design your configuration such that you do not need a ValueValidator, but sometimes it is necessary. ### Range annotations