Explain @ConfigGroup and @ConfigRoot in more details

[sarxos]

Hello.

This commit is in regards to our discussion on Zulip. See https://quarkusio.zulipchat.com/#narrow/stream/187030-users/topic/Extensions for more details.

My concern was in regards to the following statement from the "2.4.6. Configuration Example" in Extensions tutorial here https://quarkus.io/guides/extension-authors-guide.

2. The @configroot annotation indicates that this object is a configuration root group, whose property names will have a parent only of quarkus.. In this case the properties within the group will begin with quarkus.log.*.

Where the code sample looks like this:

@ConfigRoot(phase = ConfigPhase.RUN_TIME)
public class LogConfiguration {

    // ...

    /**
     * Configuration properties for the logging file handler.
     */
    FileConfig file;
}

And where point 2 states:

... indicates that this object is a configuration root group, whose property names will have a parent only of quarkus.. In this case the properties within the group will begin with quarkus.log.*.

But where is this indication? How this class is linked to quarkus.log.*? Is there some declaration missing?

---

This PR is to (hopefully) make this paragraph more clear and to document details you guys provided to me in the Zulip chat, since these details are not explained anywhere else.

[dmlloyd]

Looks mostly OK with a couple small issues.

[dmlloyd]

In fact, changing the default log file name is pretty significant and shouldn't be "hidden" as a minor doc change. I stupidly misread this change, it really is just a doc change but it is misleading because of the doc content.

[gsmet]

@sarxos could you take our comments into account and push an update? Thanks!

[gsmet]

I added a couple of minor comments.

[sarxos]

@dmlloyd @gsmet Thank you for review! Before I address your comments I would like to discuss them. Especially the log matter because I changed this intentionally to make this example less confusing. Let's discuss under the comments.

[sarxos]

@gsmet @dmlloyd I hope I addressed all of your comments. Can we do next code review iteration and merge this PR if there are no more issues here?

[gsmet]

I added a few comments. Could you check them out?

[sarxos]

@gsmet I addressed some of your comments but I would like to discuss the remaining one. For a readability sake I would like to avoid having any mention of quarkus.log in this example in terms other than a log namespace. This is the core reason why I changed this asciidoc paragraph - because it was confusing as hell :)

[gsmet]

I added a couple more comments. Once you are done with them, I think it will be OK.

Could you squash everything in one commit at the end?

Thanks!

[sarxos]

@gsmet I replaced DEFAULT_LOG_FILE_NAME with the application.log. Please let me know if this is ok and then I will squash these commits.

[cescoffier]

Waiting for CI.

[cescoffier]

@gsmet @dmlloyd are you ok with the latest changes?

[dmlloyd]

To quote @gsmet:

We need this example to compile. We can't give a doc example that doesn't compile. So if you don't want to use the constant, just use quarkus.log as it was before. It is just an example so it doesn't need to be totally similar to the code we have in Quarkus.

And round and round we go. Using logging for the example was clearly a mistake!

[sarxos]

Can we just leave it as it is now? In its current form it's sufficient to serve as an example, IMO.

[cescoffier]

@sarxos yes we keep it, the idea of using log was taken a long time ago.

[dmlloyd]

I have no opinion one way or another about the change.

Removing old review

[sarxos]

Hi @cescoffier,

What should I do with this pull request? Are we merging it or shall I close it as unnecessary? IMO it should be merged since existing example in its current form, together with related explanation, is really confusing. The changes I did are to clarify it, at least a little bit.

[sarxos]

Commits are now squashed.

The comments have been handled.

[cescoffier]

I think we are good to go. This PR clearly shows an issue with our example (log) and we may need to come with something different - less controversial as an example.