Configuration properties of type duration should include the unit when rendering the default value

Description Configuration properties such as acquisition-timeout on io.quarkus.agroal.runtime.DataSourceJdbcRuntimeConfig are declared with a default value of “5”.

@ConfigItem(defaultValue = "5")
public Optional<Duration> acquisitionTimeout = Optional.of(Duration.ofSeconds(5));

This gets rendered on documentation as type “Duration” and default value “5” but the docs don’t clarify that this is to be interpreted as seconds:

• https://quarkus.io/guides/datasource#quarkus-agroal_quarkus.datasource.jdbc.acquisition-timeout

Implementation ideas Should be possible to patch the configuration documentation generation to explicitly document as seconds, when there’s a default and it’s numeric only.

[knutwannheden]

We have the same issue with the documentation for our own Quarkus extensions, so I looked into this one. I hope you hadn’t already put work into this, @viveksahu26.

[machi1990]

since i am beginner. so can please explain me more about this issue. … On Sat, Aug 8, 2020 at 7:36 PM Manyanda Chitimbo @.***> wrote: Hi @viveksahu26 https://github.com/viveksahu26 thanks for your interest in this issue. This is part that you can look at: https://github.com/quarkusio/quarkus/tree/963519899db1691ca86fe4f278fdebf055b10204/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDoItemFinder.java#L296-L310 It should be possible to check that type is Duration.class.getName() and do the needed logic for the default value. Ping me if you have something by opening a draft PR and it we can iterate from there. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#10022 (comment)>, or unsubscribe https://github.com/notifications/unsubscribe-auth/APQTOUDF2P6R56CNBMEZ7XDR7VLXLANCNFSM4N6LKRGQ .

Context

Quarkus is able to automatically generate configuration values from code source by doing annotation scanning. The generated docs are then further processed to ouput a html file which we display in our website. For example this page https://quarkus.io/guides/all-config contains the varous configuration values for extensions in the Quarkus repo.

Issue

The issue here is that, when a configuration know is of type Duration, it can have several forms one of it being just a number in which case, we’ll consider the units to be seconds. E.g https://github.com/quarkusio/quarkus/blob/master/extensions/agroal/runtime/src/main/java/io/quarkus/agroal/runtime/DataSourceJdbcRuntimeConfig.java#L51.

The underlying default value will be Duration.ofSeconds(5) but the generated html will https://quarkus.io/guides/all-config#quarkus-agroal_quarkus.datasource.jdbc.acquisition-timeout will miss this information because it says the default value is 5 thus missing the unit. What’s desirable here is to check if the type is Duration and default value is a number, in which case we should add the unit to the final displayed value.