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

[Sanne]

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.

[daniel-augusto]

Hi @Sanne, in doc there is a tooltip for a description of Duration pattern with link to https://quarkus.io/guides/datasource#duration-note-anchor

In this section, describe a duration have a default in seconds:

You can also provide duration values starting with a number. In this case, if the value consists only of a number, the converter treats the value as seconds.

When time aren't in a second, the measure of time need explicit indicated like a javadoc of Duration show.

[viveksahu26]

I am beginner in this issue, Can you please suggest me, how to get started..

[machi1990]

Hi @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 we can iterate from there.

[viveksahu26]

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> .

[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.

[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.