[cpp-ue4] Update CppUE4ClientCodegen.java to generate docs

[monicataina]

Add support for the global properties: apiDocs and modelDocs. In case the files are generated enabling them, it will search for api_doc.mustache and model_doc.mustache to generate md documentation files.

Add an optional property for the generating call: generateReadme = true. By default, it's false and it can be omitted, so that it won't be a breaking change. If this option is used, then it will search for README.mustache and it will generate index.md file. The "index" name was chosen so that mkdocs can be used including multiple services generated via OpenAPI and this way can create a page for each of them and use the mkdocs index section feature

PR checklist

• Read the contribution guidelines.
• Pull Request title clearly describes the work in the pull request and Pull Request description provides details about how to validate the work. Missing information here may result in delayed response from the community.
• Run the following to build the project and update samples:

  ./mvnw clean package 
  ./bin/generate-samples.sh ./bin/configs/*.yaml
  ./bin/utils/export_docs_generators.sh
  

  (For Windows users, please run the script in Git BASH)
  Commit all changed files.
  This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master.
  These must match the expectations made by your contribution.
  You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/java*.
  IMPORTANT: Do NOT purge/delete any folders/files (e.g. tests) when regenerating the samples as manually written tests may be removed.
• File the PR against the correct branch: master (upcoming 7.1.0 minor release - breaking changes with fallbacks), 8.0.x (breaking changes without fallbacks)
• If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.

Mentioning C++ committee members as instructed: @ravinikam @stkrwork @etherealjoy @MartinDelille @muttleyxd

[wing328]

cc @Kahncode

[wing328]

@monicataina can you please fix https://github.com/OpenAPITools/openapi-generator/actions/runs/7912873596/job/22061320791?pr=17762 when you've time? thanks

[Kahncode]

Hello, thank you for the contribution. I am not sure to understand the impact of your change. It seems that the goal is to support a third party system called mkdocs? If so, then I would say this should not be part of the UE generator, and should be it's own standalone. The UE generator should generate c++ code that is documented as best possible, and then you can use c++ tooling to extract the docs from the code.

…

On Wed, Feb 28, 2024, 11:02 William Cheng ***@***.***> wrote: @monicataina <https://github.com/monicataina> can you please fix https://github.com/OpenAPITools/openapi-generator/actions/runs/7912873596/job/22061320791?pr=17762 when you've time? thanks — Reply to this email directly, view it on GitHub <#17762 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ALVKNGUAFYA6CWYHB7J6JDDYV2T55AVCNFSM6AAAAABCVDF7S6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSNRYGE3TKNBQHA> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[wing328]

It seems that the goal is to support a third party system called mkdocs

The PR aims to add auto-generated markdown documentation for API and models. Other generators already support something similar, e.g. https://github.com/OpenAPITools/openapi-generator/blob/master/samples/client/petstore/java/native/docs/PetApi.md

I think new users of the client will find these auto-generated documentation useful as a starting point.

[Kahncode]

Hello William, I have to say I have mixed feelings on this idea. This adds extra complexity that needs to be maintained, and does not contribute to the main goal of the generator. I would like to add two arguments for your consideration : Unreal developers have a c++ code base and use their own tooling to extract a complete documentation of their code. The generator aims to have most of the documentation directly as comments in the code, which provides the best guidance and is automatically integrated within our tools. On the other hand, this markdown format makes an opinionated choice about documentation tooling, and couples it with the unreal generator. Instead, why not have the specific markdown format be a generator of its own, preserving simplicity and atomicity in each of the generators. I believe composing generators here is better than extending single purpose ones. Thanks for your consideration.

…

On Wed, Feb 28, 2024, 17:56 William Cheng ***@***.***> wrote: It seems that the goal is to support a third party system called mkdocs The PR aims to add auto-generated markdown documentation for API and models. Other generators already support something similar, e.g. https://github.com/OpenAPITools/openapi-generator/blob/master/samples/client/petstore/java/native/docs/PetApi.md I think new users of the client will find these auto-generated documentation useful as a starting point. — Reply to this email directly, view it on GitHub <#17762 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ALVKNGUM6SPYSHQCOYCTOH3YV4ENZAVCNFSM6AAAAABCVDF7S6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSNRYG4ZTAOBXG4> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[wing328]

what about making it an option? e.g. generateDocs=true will generate the markdown documentation.

I think @monicataina will help maintain the auto-generated markdown doc moving forward.

[Kahncode]

Again, I find this is unrelated to unreal engine. If you find that this options is valuable to most if not all generators, why not provide it at global level by making this a feature of openapi generator itself? In any case, my view is that this does not belong in this generator, or any other except its own. It feels what we're looking for here is the ability to combine and compose generators, and I fully agree this could be an interesting feature, but it should not require to modify specific generators for it. For example let me choose ue4-cpp + doxygen. Or ue4-cpp + mkdocs. Having it inside the generators is, in my opinion, a bad architectural decision and opening a pandora's box of crossovers we probably don't want to have to maintain. Let the generators do one thing only and do it well. Respectfully,

…

On Thu, Feb 29, 2024, 09:06 William Cheng ***@***.***> wrote: what about making it an option? e.g. generateDocs=true will generate the markdown documentation. I think @monicataina <https://github.com/monicataina> will help maintain the auto-generated markdown doc moving forward. — Reply to this email directly, view it on GitHub <#17762 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ALVKNGRIWVTRAWAZNC6DMMLYV2GJJAVCNFSM6AAAAABCVDF7S6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSNZQGI3DMOBUG4> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[wing328]

Again, I find this is unrelated to unreal engine. If you find that this
options is valuable to most if not all generators, why not provide it at
global level by making this a feature of openapi generator itself?

This feature (auto-generated doc) is indeed available in the global level (enabled by default) and there's an option to skip it.

Most client generators have auto-generated documentation with code samples to onboard new users more easily.

If you feel strongly against adding this feature to this generator, I'm totally ok with it and definitely won't force you to accept this PR.

[monicataina]

Hello, I apologize for the delay.

@Kahncode: I understand that you have mixed feelings about my PR. I appreciate your concern for keeping the code clean and avoiding overcomplicating it. Thank you for the effort you have put into making the UE ClientCodegen better!

Regarding my PR, I understand that the feature already exists on a global view. However, upon checking, I found that it cannot automatically detect if those files exist in your mustache template folder and it doesn't automatically generate the .md files.

As for the mkdocs usage, the only custom thing there is that I generated the README into an "index.md" file. If you find the rest of my PR useful, I can change it to a more common name like "README.md".

@wing328: It seems that there are some questions about the docs generator being a supported feature, and the need to implement a similar thing for each ClientCodegen. Do you think it's possible to include such a code internally in a common place, while keeping all properties optional (like the existing apiDocs and modelDocs, as well as the property suggested in this PR: generateReadme)?

[Kahncode]

Hello, apologies for the delay again in response.

@monicataina I think in this case the mkdocs generator should be fully separated from the unreal generator. It should provide its own mustache files and perhaps generate in its own folder such as mkdocs/README.md, in order to avoid problems where the template used in conjunction has its own. Then you wouldn't have to test whether specific files are provided in the mustache template or not.

In general I strongly believe that this feature needs to be packaged either into its own generator or as a global feature of openapi-generator, having to modify each generator to support mkdocs seems like the wrong approach, especially considering the many other ways a developer could want to format their documentation. In this case I would like to keep this out of the Unreal generator.

I hope you understand my position.

[monicataina]

@wing328 Can you help us with a global solution here?
In DefaultGenerator.java there are checks if apiDocs and modelDocs properties are enabled by users:

generateModelDocumentation = GlobalSettings.getProperty(CodegenConstants.MODEL_DOCS) != null ? Boolean.valueOf(GlobalSettings.getProperty(CodegenConstants.MODEL_DOCS)) : getGeneratorPropertyDefaultSwitch(CodegenConstants.MODEL_DOCS, true);
generateApiDocumentation = GlobalSettings.getProperty(CodegenConstants.API_DOCS) != null ? Boolean.valueOf(GlobalSettings.getProperty(CodegenConstants.API_DOCS)) : getGeneratorPropertyDefaultSwitch(CodegenConstants.API_DOCS, true);

Question 1: Can we have a similar code in DefaultGenerator.java for a property for generating readme?

DocumentationFeature.API and DocumentationFeature.Model are already added in DefaultCodegen.java:

 .includeDocumentationFeatures(
                        DocumentationFeature.Api, DocumentationFeature.Model
                        // README is template specific
                )

Question 2: Why DocumantationFeature.Readme is missing from the default setting from DefaultCodegen.java? Wouldn't it be nice to have it there by default too?

For other languages, both modelDocTemplateFiles and apiDocTemplateFiles are added in an abstract class. The DocumantationFeature.Readme is also added via modifyFeatureSet in the same abstract class (example: AbstractJavaCodegen.java)

        modelDocTemplateFiles.put(
                "model_doc.mustache",  // the template to use
                ".md"); // the extension for each file to write
        apiDocTemplateFiles.put(
                "api_doc.mustache", // the template to use
                ".md"); // the extension for each file to write

Question 3: Can we add them in AbstractCppCodegen too?
Question 4: Can we have a similar implementation in DefaultGenerator to support a readmeDocTemplateFiles?