A preview for this pull request is available at https://cdn.rawgit.com/Spongy/SpongeDocs-PRs/ccf2104/.

Here are some links to the pages that were modified:

• modified: https://cdn.rawgit.com/Spongy/SpongeDocs-PRs/ccf2104/plugin/configuration/index.html
• modified: https://cdn.rawgit.com/Spongy/SpongeDocs-PRs/ccf2104/plugin/configuration/loaders.html
• modified: https://cdn.rawgit.com/Spongy/SpongeDocs-PRs/ccf2104/plugin/configuration/nodes.html
• modified: https://cdn.rawgit.com/Spongy/SpongeDocs-PRs/ccf2104/plugin/configuration/serialization.html

Since the preview frequently changes, please link to this comment, not to the direct url to the preview.

@Simon_Flash mentioned on Discord that there is a different (recommended) way of checking whether the config is empty.

Solution 1A ( suggested )

@Inject @DefaultConfig(sharedRoot = true)
private Path configPath;
@Inject @DefaultConfig(sharedRoot = true)
private ConfigurationLoader<CommentedConfigurationNode> configManager;

if (Files.exists(configPath)) {
	rootNode = this.configManager.load();
} else {
	this.logger.info("No config found - loading default");
	URL jarConfigFile = Sponge.getAssetManager().getAsset("defaultConfig.conf").get().getUrl();
	ConfigurationLoader<CommentedConfigurationNode> defaultLoader =
			HoconConfigurationLoader.builder().setURL(jarConfigFile).build();
	rootNode = defaultLoader.load();
}

Solution 1B ( not tested )

@Inject @DefaultConfig(sharedRoot = true)
private Path configPath;
@Inject @DefaultConfig(sharedRoot = true)
private ConfigurationLoader<CommentedConfigurationNode> configManager;

if (!Files.exists(configPath)) {
    this.logger.info("No config found - loading default");
    Asset jarConfigFile = Sponge.getAssetManager().getAsset("defaultConfig.conf").get();
    jarConfigFile.copyToFile(configPath);
}
rootNode = this.configManager.load();

Solution 2

@Inject @DefaultConfig(sharedRoot = true)
private ConfigurationLoader<CommentedConfigurationNode> configManager;

rootNode = this.configManager.load();
if (!rootNode.hasMapChildren()) {
	this.logger.info("No config found - loading default");
	final URL jarConfigFile = Sponge.getAssetManager().getAsset("defaultConfig.conf").get().getUrl();
	final ConfigurationLoader<CommentedConfigurationNode> defaultLoader =
			HoconConfigurationLoader.builder().setURL(jarConfigFile).build();
	rootNode = defaultLoader.load();
}

I prefer the later variant as

• it also works with completely empty files
• it does not need a new injection for only that single usecase
• it is easier to implement loading the default in case the normal one cannot be loaded due to an IOEx

Which variant should we use in the docs as the recommended way?

Simon_Flash's reasons for suggesting Solution 1 as stated on discord, just copied here so it does not get lost:

1. Prefer Files#exists(Path) because that's correct. Just because it works doesn't mean it's correct. When you insert a default config, in my opinion it should only be because the file doesn't exist, not because it's empty. Your hasMapChildren method will not always work.

2. The AssetManager doesn't return Paths, it returns an Asset. You should copy that asset to the path of the config file if and only if it doesn't exist, then load the config through the path normally. Asset has a variety of copyTo methods for this.

3. Saving the file to disk will always happen. I find there being more boilerplate to inject things in my opinion.

The main work for this change has been done. So we can start the review period.

There are two things that are up for/need discussion though:

• First the recommended way of loading a default config from the jar (asset).
• What is the recommended way of serializing Text: via Config, inline json, extra Json files (per entry?), or via minecraft lang files? Or don't we provide a recommendation until the TextTemplates have been improved?

Some last change requests?