Clarify the role of snippetsDir as a task input and output

[galmegiz]

In official Spring REST docs "Build configuration", there is a block that says

        "test {
                  outputs.dir snippetsDir
        }". //Configure the test task to add the snippets directory as an output.

In stackoverflow question

Wilkinson stated, "Setting the generated snippets directory as an output of the test task and an input of the Asciidoctor task allows Gradle to figure out task dependencies and perform accurate up-to-date checks."

I understand the intention behind that statement, but many people are interpreting test task block as defining the output directory for generated snippets, which is causing confusion and difficulties for them.(Many people mistakenly believe that they can change the snippet generation path by modifying outputs.dir.)

If the dependencies are properly managed through "depends on," I think the use of outputs.dir and becomes unnecessary in this case.

If that statement is not essential and can lead to confusion, it might be a good idea to remove it from the 'Spring Rest docs' manual. Indeed, since it is not intended to be a comprehensive guide on using Gradle, it may be appropriate to omit detailed instructions related to Gradle configuration from the manual. Or it would be beneficial to provide additional explanatory information to clarify the purpose and usage of outputs.dir.

In conclusion, I propose removing the "outputs.dir snippetsDir" phrase from the test task block in the manual.

[wilkinsona]

I understand the intention behind that statement, but many people are interpreting test task block as defining the output directory for generated snippets, which is causing confusion and difficulties for them.(Many people mistakenly believe that they can change the snippet generation path by modifying outputs.dir.)

Can you provide some examples of the confusion? I've seen very little myself.

If the dependencies are properly managed through "depends on," I think the use of outputs.dir and becomes unnecessary in this case.

I believe it is necessary. Gradle uses task inputs and outputs to determine which tasks need to run as part of an incremental build. If the task that is running Spring REST Docs and producing the snippets is not configured with the snippets directory as an output, incremental builds will no work correctly.

[galmegiz]

• As you said, it can be a little confusing. But, People who are not familiar with Gradle may mistakenly assume that outputs.dir specifies the generation path for snippets. (Even though some time has passed, above stackoverflow question also misunderstand the reference). Maybe... During the translation process of the reference in Korea, there could have been even more room for misunderstanding.
• I think the presence of information related to optimizing Gradle builds in the Spring REST Docs reference seems to be causing confusion.
• If incremental build in Gradle is crucial when using Spring REST Docs & asciidoctor, it might be helpful to provide a more detailed explanation. ex) "Configure the test task to include the snippets directory in the incremental build process."
• While it may seem like a minor difference to some, providing a more detailed explanation can be immensely helpful for beginners.