From 869d95f5c87b325976620db53b7b469487f1bbd8 Mon Sep 17 00:00:00 2001 From: dfsek Date: Sun, 25 Apr 2021 16:53:11 -0700 Subject: [PATCH] begin work on automatic config docs --- common/build.gradle.kts | 72 +++++++++++++++++++ .../provider/BiomePipelineTemplate.java | 12 ++++ .../sampler/templates/DomainWarpTemplate.java | 17 +++++ .../sampler/templates/SamplerTemplate.java | 3 + .../templates/noise/GaborNoiseTemplate.java | 12 ++++ .../terra/config/pack/ConfigPackTemplate.java | 28 ++++++++ .../terra/config/templates/FloraTemplate.java | 2 +- 7 files changed, 145 insertions(+), 1 deletion(-) diff --git a/common/build.gradle.kts b/common/build.gradle.kts index ec58b60e9..5e156d936 100644 --- a/common/build.gradle.kts +++ b/common/build.gradle.kts @@ -1,10 +1,19 @@ import com.dfsek.terra.configureCommon +import com.github.javaparser.ast.body.FieldDeclaration +import com.github.javaparser.ast.expr.StringLiteralExpr +import com.github.javaparser.StaticJavaParser plugins { `java-library` `maven-publish` } +buildscript { + dependencies { + classpath("com.github.javaparser:javaparser-symbol-solver-core:3.20.2") + } +} + configureCommon() group = "com.dfsek.terra.common" @@ -51,4 +60,67 @@ publishing { } } } +} + +tasks.create("tectonicDocs") { + group = "terra" + println("Scanning sources...") + + val docs = HashMap() + + sourceSets.forEach { sourceSet -> + sourceSet.java.forEach { file -> + val doc = StringBuilder() + val name = file.name.substring(0, file.name.length - 5) + val unit = StaticJavaParser.parse(file) + + doc.append("# $name\n") + + unit.getClassByName(name).ifPresent { declaration -> + declaration.javadoc.ifPresent { + doc.append("${sanitizeJavadoc(it.toText())} \n") + } + declaration.extendedTypes.forEach { + if(!it.name.asString().equals("AbstractableTemplate")) { + doc.append("Inherits from [${it.name}](./${it.name})\n") + } + } + doc.append("\n") + } + + var applicable = false + unit.findAll(FieldDeclaration::class.java).filter { it.isAnnotationPresent("Value") }.forEach { fieldDeclaration -> + doc.append("## ${(fieldDeclaration.getAnnotationByName("Value").get().childNodes[1] as StringLiteralExpr).asString()}\n") + + if(fieldDeclaration.isAnnotationPresent("Default")) { + doc.append("* Default value: ${fieldDeclaration.variables[0]} \n") + } + val type =fieldDeclaration.commonType.asString() + doc.append("* Type: [$type](./$type) \n") + doc.append("\n") + + fieldDeclaration.javadoc.ifPresent { + doc.append(sanitizeJavadoc(it.toText())) + } + doc.append("\n\n") + applicable = true + } + val s = doc.toString() + if (s.isNotEmpty() && applicable) docs[name] = s + } + } + println("Done. Generated ${docs.size} files") + + val docsDir = File(buildDir, "tectonic") + docsDir.mkdirs() + docs.forEach { + val save = File(docsDir, "${it.key}.md") + if (save.exists()) save.delete() + save.createNewFile() + save.writeText(it.value) + } +} + +fun sanitizeJavadoc(doc:String):String { + return doc.replace("

", "").replace("<", "\\<").replace(">", "\\>") } \ No newline at end of file diff --git a/common/src/main/java/com/dfsek/terra/config/loaders/config/biome/templates/provider/BiomePipelineTemplate.java b/common/src/main/java/com/dfsek/terra/config/loaders/config/biome/templates/provider/BiomePipelineTemplate.java index 31f448553..c745c007d 100644 --- a/common/src/main/java/com/dfsek/terra/config/loaders/config/biome/templates/provider/BiomePipelineTemplate.java +++ b/common/src/main/java/com/dfsek/terra/config/loaders/config/biome/templates/provider/BiomePipelineTemplate.java @@ -11,16 +11,28 @@ import com.dfsek.terra.api.world.biome.provider.StandardBiomeProvider; import java.util.List; +/** + * Configures a biome pipeline. + */ @SuppressWarnings({"FieldMayBeFinal", "unused"}) public class BiomePipelineTemplate extends BiomeProviderTemplate { private final TerraPlugin main; + /** + * Initial size of biome pipeline chunks. + */ @Value("pipeline.initial-size") @Default private int initialSize = 2; + /** + * Mutator stages to be used in this biome pipeline. + */ @Value("pipeline.stages") private List stages; + /** + * Biome source to initialize the pipeline. + */ @Value("pipeline.source") private SourceSeeded source; diff --git a/common/src/main/java/com/dfsek/terra/config/loaders/config/sampler/templates/DomainWarpTemplate.java b/common/src/main/java/com/dfsek/terra/config/loaders/config/sampler/templates/DomainWarpTemplate.java index 3607c17e9..15df3fda7 100644 --- a/common/src/main/java/com/dfsek/terra/config/loaders/config/sampler/templates/DomainWarpTemplate.java +++ b/common/src/main/java/com/dfsek/terra/config/loaders/config/sampler/templates/DomainWarpTemplate.java @@ -6,18 +6,35 @@ import com.dfsek.terra.api.math.noise.NoiseSampler; import com.dfsek.terra.api.math.noise.samplers.DomainWarpedSampler; import com.dfsek.terra.api.util.seeded.NoiseSeeded; +/** + * Defines a domain-warped noise function. + */ @SuppressWarnings({"unused", "FieldMayBeFinal"}) public class DomainWarpTemplate extends SamplerTemplate { + /** + * Noise function used to warp input function. + */ @Value("warp") private NoiseSeeded warp; + /** + * Input function (function to be warped) + */ @Value("function") private NoiseSeeded function; + /** + * Salt for both warp function and + * input function. + */ @Value("salt") @Default private int salt = 0; + /** + * Amplitude of warping. Values provided by + * the warp function are multiplied by this constant. + */ @Value("amplitude") @Default private double amplitude = 1; diff --git a/common/src/main/java/com/dfsek/terra/config/loaders/config/sampler/templates/SamplerTemplate.java b/common/src/main/java/com/dfsek/terra/config/loaders/config/sampler/templates/SamplerTemplate.java index 7914ec957..89e81672e 100644 --- a/common/src/main/java/com/dfsek/terra/config/loaders/config/sampler/templates/SamplerTemplate.java +++ b/common/src/main/java/com/dfsek/terra/config/loaders/config/sampler/templates/SamplerTemplate.java @@ -10,6 +10,9 @@ import com.dfsek.terra.api.util.seeded.NoiseSeeded; @SuppressWarnings("FieldMayBeFinal") public abstract class SamplerTemplate implements ValidatedConfigTemplate, ObjectTemplate, NoiseSeeded { + /** + * Number of dimensions for this sampler. + */ @Value("dimensions") @Default private int dimensions = 2; diff --git a/common/src/main/java/com/dfsek/terra/config/loaders/config/sampler/templates/noise/GaborNoiseTemplate.java b/common/src/main/java/com/dfsek/terra/config/loaders/config/sampler/templates/noise/GaborNoiseTemplate.java index b15aa75cd..76bee6ef1 100644 --- a/common/src/main/java/com/dfsek/terra/config/loaders/config/sampler/templates/noise/GaborNoiseTemplate.java +++ b/common/src/main/java/com/dfsek/terra/config/loaders/config/sampler/templates/noise/GaborNoiseTemplate.java @@ -5,15 +5,27 @@ import com.dfsek.tectonic.annotations.Value; import com.dfsek.terra.api.math.noise.NoiseSampler; import com.dfsek.terra.api.math.noise.samplers.noise.GaborNoiseSampler; +/** + * Defines a Gabor noise function. + */ public class GaborNoiseTemplate extends NoiseTemplate { + /** + * Rotation to apply to noise. Only has noticeable effects in anisotropic mode. + */ @Value("rotation") @Default private double rotation = 0.25; + /** + * Whether to use anisotropic or isotropic algorithm. + */ @Value("isotropic") @Default private boolean isotropic = true; + /** + * Standard deviation of result values. + */ @Value("deviation") @Default private double deviation = 1.0; diff --git a/common/src/main/java/com/dfsek/terra/config/pack/ConfigPackTemplate.java b/common/src/main/java/com/dfsek/terra/config/pack/ConfigPackTemplate.java index bfebcb717..4bb3122db 100644 --- a/common/src/main/java/com/dfsek/terra/config/pack/ConfigPackTemplate.java +++ b/common/src/main/java/com/dfsek/terra/config/pack/ConfigPackTemplate.java @@ -15,24 +15,52 @@ import java.util.Set; @SuppressWarnings({"unused", "FieldMayBeFinal"}) public class ConfigPackTemplate implements ConfigTemplate { + + /** + * The ID of the config pack. + */ @Value("id") private String id; + /** + * Noise functions to be made available + * to noise equations in the config pack. + *

+ * Keys are Paralithic function IDs, + * values are noise functions. + */ @Value("noise") private Map noiseBuilderMap; + /** + * Addons this pack depends on. + */ @Value("addons") @Default private Set addons = new HashSet<>(); + /** + * Variables to be made available + * to noise equations in the config pack. + *

+ * Keys are variable IDs, + * values are variable values. + */ @Value("variables") @Default private Map variables = new HashMap<>(); + /** + * Whether to enable beta noise + * carvers. + */ @Value("beta.carving") @Default private boolean betaCarvers = false; + /** + * + */ @Value("functions") @Default private LinkedHashMap functions = new LinkedHashMap<>(); diff --git a/common/src/main/java/com/dfsek/terra/config/templates/FloraTemplate.java b/common/src/main/java/com/dfsek/terra/config/templates/FloraTemplate.java index 8e1564e4a..5c1deb15a 100644 --- a/common/src/main/java/com/dfsek/terra/config/templates/FloraTemplate.java +++ b/common/src/main/java/com/dfsek/terra/config/templates/FloraTemplate.java @@ -32,7 +32,7 @@ public class FloraTemplate extends AbstractableTemplate { @Value("irrigable") @Abstractable @Default - private MaterialSet irrigable = null; + private MaterialSet irrigable = new MaterialSet(); @Value("rotatable") @Abstractable