Codegen API and docs improvements

[ppalaga]

Thoughts that are coming to my mind while working on my first CodeGenProvider. Some of those may evolve to separate issues if there is enough agreement about their usefulness.

1. Pretty please add some basic JavaDoc on all CodeGenProvider API classes and methods:

• io.quarkus.deployment.CodeGenContext - no single line of JavaDoc. Esp. it would be nice to know what outDir(), workDir() and inputDir() are good for. Are they absolute or relative (to what?) Examples would be nice.
• io.quarkus.bootstrap.model.ApplicationModel - no single line of JavaDoc
• CodeGenProvider - what is its life cycle? May I keep some state? May I assume the individual methods to be called in some particular order? May I return different values from inputExtension() and inputDirectory() at different times? Some general info and implications about invoking from Maven/Gradle vs. invoking in dev mode would be nice.

2. The JavaDoc of CodeGenProvider.[inputExtension|inputDirectory]() awakes the impression that one can support only one kind of files under a single src/main subdirectory. That's very limiting. Users may choose to name their files however they like (including no extension at all) for whatever good and bad reasons. Sometimes, they may want to have them under src/main/resources, because they need them in the app and some other time they may want the opposite. It would be nice if CodeGenProviders could advertise the set of their input files using Ant-like FileSets defined via directory/includes/excudes. At the same time, it should be possible for a CodeGenProvider to output a FileSet based on directories, includes and excludes defined in build time application configuration.

   Making the code generation configuration driven is currently possible (see also 3.), but I doubt the generation is re-triggered in dev mode if the user changes some relevant config key in application.properties. This can be seen as a bug from end user perspective and I do not see any way how I could fix this with the current API.

   @jamesnetherton mentioned that a potential CodeGenProviders for Salesforce DTO would be 100% config driven. No input files at all beyond application.properties. With the current API, this should be done with inputDir resources and inputExtension properties, right? Shouldn't we maybe let CodeGenProviders to advertise their input properties?

3. Make it possible to access build time config POJOs from CodeGenProvider. Currently CodeGenProvider.trigger() gives an access to a org.eclipse.microprofile.config.Config instance, but there is no (correct me if I am wrong) way to get my config POJO with all defaults set. I have to check the optionals and set defaults manually. moved to a separate issue: Allow accessing build time config POJOs from a CodeGenProvider #35962

4. generate-code and code generation phase are mentioned several times on various quarkus.io pages, but still it would be nice to have a paragraph somewhere, that would explain the general concept of code generation - that it is extension driven, that generate-code must be there for Maven projects, the limitations of source folders and extensions, support during normal builds and dev mode.

5. wsdl2java that I am wrapping in my CodeGenProvider has its own plugin SPI. It does not look like there is a way how end users could add custom artifacts to the classpath of my CodeGenProvider? Is there any chance to have this, perhaps as a part of Maven/Gradle config of the generate-code mojo? Edit: I decided to wrap all those plugins in a separate extension and advised the users to add it whenever they need any of the plugins. I need that extension anyway, because there is a jar ('cxf-xjc-runtime') that the code generated by those plugins requires.

[quarkus-bot]

/cc @Sanne (core), @aloubyansky (core), @gsmet (core), @radcortez (core), @stuartwdouglas (core)

[maxandersen]

@ppalaga this is worth post on quarkus-dev I would think!

[andreaTP]

Writing my first CodeGenProvider and I'm here as well, I share most of the issues already expressed above.
More questions:

• how to support multiple file extensions? e.g. json and yaml -> one option should be declaring 2 CodeGenProvider sharing the generation logic
• how to support "remote" files? It's probably possible to automate something with the download-maven-plugin but it's extremely tedious to configure, being able to define a source and/or a url has been demonstrated to be a convenient tradeoff

What's the Lifecycle of a CodeGenProvider object, especially in quarkus:dev mode?