This is an automated email from the ASF dual-hosted git repository. jamesnetherton pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/camel-quarkus.git
commit e823080451c0a7a36728cdc720ced0fd74ba89d4 Author: Peter Palaga <[email protected]> AuthorDate: Tue Aug 20 14:55:46 2024 +0200 Add missing Duration and MemSize type notes to the docs --- .../ROOT/pages/reference/extensions/core.adoc | 20 +++++++- .../quarkus/maven/UpdateExtensionDocPageMojo.java | 55 +++++++++++++++++----- .../doc-templates/extension-doc-page.adoc | 31 ++++++++++++ 3 files changed, 93 insertions(+), 13 deletions(-) diff --git a/docs/modules/ROOT/pages/reference/extensions/core.adoc b/docs/modules/ROOT/pages/reference/extensions/core.adoc index 9e2a080573..7aca6f73da 100644 --- a/docs/modules/ROOT/pages/reference/extensions/core.adoc +++ b/docs/modules/ROOT/pages/reference/extensions/core.adoc @@ -410,7 +410,7 @@ Whether type converter statistics are enabled. By default, type converter utiliz |icon:lock[title=Fixed at build time] [[quarkus.camel.main.shutdown.timeout]]`link:#quarkus.camel.main.shutdown.timeout[quarkus.camel.main.shutdown.timeout]` A timeout (with millisecond precision) to wait for `CamelMain++#++stop()` to finish -| link:https://docs.oracle.com/en/java/javase/17/docs/api/java/time/Duration.html[`Duration`] link:#duration-note-anchor-{summaryTableId}[icon:question-circle[title=More information about the Duration format]] +| link:https://docs.oracle.com/en/java/javase/17/docs/api/java/time/Duration.html[`Duration`] link:#duration-note-anchor-core[icon:question-circle[title=More information about the Duration format]] | `PT3S` |icon:lock[title=Fixed at build time] [[quarkus.camel.main.arguments.on-unknown]]`link:#quarkus.camel.main.arguments.on-unknown[quarkus.camel.main.arguments.on-unknown]` @@ -423,3 +423,21 @@ The action to take when `CamelMain` encounters an unknown argument. fail - Print [.configuration-legend] {doc-link-icon-lock}[title=Fixed at build time] Configuration property fixed at build time. All other configuration properties are overridable at runtime. +[NOTE] +[id=duration-note-anchor-core] +.About the Duration format +==== +To write duration values, use the standard `java.time.Duration` format. +See the link:https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html#parse(java.lang.CharSequence)[Duration#parse() Java API documentation] for more information. + +You can also use a simplified format, starting with a number: + +* If the value is only a number, it represents time in seconds. +* If the value is a number followed by `ms`, it represents time in milliseconds. + +In other cases, the simplified format is translated to the `java.time.Duration` format for parsing: + +* If the value is a number followed by `h`, `m`, or `s`, it is prefixed with `PT`. +* If the value is a number followed by `d`, it is prefixed with `P`. +==== + diff --git a/tooling/maven-plugin/src/main/java/org/apache/camel/quarkus/maven/UpdateExtensionDocPageMojo.java b/tooling/maven-plugin/src/main/java/org/apache/camel/quarkus/maven/UpdateExtensionDocPageMojo.java index efe64d7d20..e15ae3457f 100644 --- a/tooling/maven-plugin/src/main/java/org/apache/camel/quarkus/maven/UpdateExtensionDocPageMojo.java +++ b/tooling/maven-plugin/src/main/java/org/apache/camel/quarkus/maven/UpdateExtensionDocPageMojo.java @@ -198,8 +198,15 @@ public class UpdateExtensionDocPageMojo extends AbstractDocGeneratorMojo { ext.getQuarkusAwsClientFqClassName(), ext.getRuntimePomXmlPath())); model.put("activatesQuarkusLangChain4jBom", ext.getRuntimeArtifactId().contains("langchain4j")); - model.put("configOptions", - listConfigOptions(runtimeModuleDir, deploymentModuleDir, multiModuleProjectDirectory.toPath())); + final List<ConfigItem> configOptions = listConfigOptions( + runtimeModuleDir, + deploymentModuleDir, + multiModuleProjectDirectory.toPath(), + ext.getRuntimeArtifactIdBase()); + model.put("configOptions", configOptions); + model.put("hasDurationOption", configOptions.stream().anyMatch(ConfigItem::isTypeDuration)); + model.put("hasMemSizeOption", configOptions.stream().anyMatch(ConfigItem::isTypeMemSize)); + model.put("configOptions", configOptions); model.put("humanReadableKind", new TemplateMethodModelEx() { @Override public Object exec(List arguments) throws TemplateModelException { @@ -464,7 +471,7 @@ public class UpdateExtensionDocPageMojo extends AbstractDocGeneratorMojo { } static List<ConfigItem> listConfigOptions(Path runtimeModuleDir, Path deploymentModuleDir, - Path multiModuleProjectDirectory) { + Path multiModuleProjectDirectory, String artifactIdBase) { final List<ConfigProperty> result = new ArrayList<>(); final List<Path> targetDirectories = Stream.of(runtimeModuleDir, deploymentModuleDir) @@ -496,7 +503,7 @@ public class UpdateExtensionDocPageMojo extends AbstractDocGeneratorMojo { Collections.sort(result); return result.stream() - .map(cp -> ConfigItem.of(cp, javadocRepository)) + .map(cp -> ConfigItem.of(cp, javadocRepository, artifactIdBase)) .collect(Collectors.toList()); } @@ -568,12 +575,14 @@ public class UpdateExtensionDocPageMojo extends AbstractDocGeneratorMojo { private final String illustration; private final String configDoc; private final String type; + private final boolean typeDuration; + private final boolean typeMemSize; private final String defaultValue; private final boolean optional; private final String since; private final String environmentVariable; - public static ConfigItem of(ConfigProperty configDocItem, JavadocRepository javadocRepository) { + public static ConfigItem of(ConfigProperty configDocItem, JavadocRepository javadocRepository, String artifactIdBase) { final Optional<JavadocElement> javadoc = javadocRepository .getElement(configDocItem.getSourceClass(), configDocItem.getSourceName()); if (javadoc.isEmpty()) { @@ -583,19 +592,22 @@ public class UpdateExtensionDocPageMojo extends AbstractDocGeneratorMojo { final String adocSource = LINK_PATTERN.matcher(javadoc.get().description()).replaceAll("xref:$1.adoc"); final String illustration = configDocItem.getPhase().isFixedAtBuildTime() ? "icon:lock[title=Fixed at build time]" : ""; + final TypeInfo typeInfo = typeContent(configDocItem, javadocRepository, true, artifactIdBase); return new ConfigItem( configDocItem.getPath(), illustration, adocSource, - typeContent(configDocItem, javadocRepository, true), + typeInfo.description, + typeInfo.isDuration, + typeInfo.isMemSize, configDocItem.getDefaultValue(), configDocItem.isOptional(), javadoc.get().since(), configDocItem.getEnvironmentVariable()); } - static String typeContent(ConfigProperty configProperty, JavadocRepository javadocRepository, - boolean enableEnumTooltips) { + static TypeInfo typeContent(ConfigProperty configProperty, JavadocRepository javadocRepository, + boolean enableEnumTooltips, String artifactIdBase) { String typeContent = ""; if (configProperty.isEnum() && enableEnumTooltips) { @@ -610,15 +622,22 @@ public class UpdateExtensionDocPageMojo extends AbstractDocGeneratorMojo { typeContent = "List of " + typeContent; } + boolean isDuration = false; + boolean isMemSize = false; if (Duration.class.getName().equals(configProperty.getType())) { typeContent += " " + String.format(MORE_INFO_ABOUT_TYPE_FORMAT, - "duration-note-anchor-{summaryTableId}", Duration.class.getSimpleName()); + "duration-note-anchor-" + artifactIdBase, Duration.class.getSimpleName()); + isDuration = true; } else if (Types.MEMORY_SIZE_TYPE.equals(configProperty.getType())) { typeContent += " " + String.format(MORE_INFO_ABOUT_TYPE_FORMAT, - "memory-size-note-anchor-{summaryTableId}", "MemorySize"); + "memory-size-note-anchor-" + artifactIdBase, "MemorySize"); + isMemSize = true; } - return typeContent; + return new TypeInfo(typeContent, isDuration, isMemSize); + } + + public record TypeInfo(String description, boolean isDuration, boolean isMemSize) { } static String joinEnumValues(ConfigProperty configProperty, JavadocRepository javadocRepository) { @@ -640,12 +659,16 @@ public class UpdateExtensionDocPageMojo extends AbstractDocGeneratorMojo { .replace(":", "\\:").replace("[", "\\]").replace("]", "\\]"); } - public ConfigItem(String key, String illustration, String configDoc, String type, String defaultValue, + public ConfigItem(String key, String illustration, String configDoc, + String type, boolean typeDuration, boolean typeMemSize, + String defaultValue, boolean optional, String since, String environmentVariable) { this.key = key; this.illustration = illustration; this.configDoc = configDoc; this.type = type; + this.typeDuration = typeDuration; + this.typeMemSize = typeMemSize; this.defaultValue = defaultValue; this.optional = optional; this.since = since; @@ -668,6 +691,14 @@ public class UpdateExtensionDocPageMojo extends AbstractDocGeneratorMojo { return type; } + public boolean isTypeDuration() { + return typeDuration; + } + + public boolean isTypeMemSize() { + return typeMemSize; + } + public String getDefaultValue() { return defaultValue; } diff --git a/tooling/maven-plugin/src/main/resources/doc-templates/extension-doc-page.adoc b/tooling/maven-plugin/src/main/resources/doc-templates/extension-doc-page.adoc index da50605c68..d36cee6d3f 100644 --- a/tooling/maven-plugin/src/main/resources/doc-templates/extension-doc-page.adoc +++ b/tooling/maven-plugin/src/main/resources/doc-templates/extension-doc-page.adoc @@ -182,6 +182,37 @@ class Unremovable[=quarkusAwsClient.clientClassSimpleName] { [.configuration-legend] {doc-link-icon-lock}[title=Fixed at build time] Configuration property fixed at build time. All other configuration properties are overridable at runtime. +[#if hasDurationOption] + +[NOTE] +[id=duration-note-anchor-[=artifactIdBase]] +.About the Duration format +==== +To write duration values, use the standard `java.time.Duration` format. +See the link:https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html#parse(java.lang.CharSequence)[Duration#parse() Java API documentation] for more information. + +You can also use a simplified format, starting with a number: + +* If the value is only a number, it represents time in seconds. +* If the value is a number followed by `ms`, it represents time in milliseconds. + +In other cases, the simplified format is translated to the `java.time.Duration` format for parsing: + +* If the value is a number followed by `h`, `m`, or `s`, it is prefixed with `PT`. +* If the value is a number followed by `d`, it is prefixed with `P`. +==== +[/#if] +[#if hasMemSizeOption] + +[NOTE] +[id=memory-size-note-anchor-[=artifactIdBase]] +.About the MemorySize format +==== +A size configuration option recognizes strings in this format (shown as a regular expression): `[0-9]+[KkMmGgTtPpEeZzYy]?`. + +If no suffix is given, assume bytes. +==== +[/#if] [/#if] [/#if]
