[docs] Document --enable-post-process-file

[henrebotha]

There is no proper documentation for this tool anywhere.

[pixelshaded]

https://openapi-generator.tech/docs/usage/
https://github.com/OpenAPITools/openapi-generator/tree/master/docs

How are these not proper documentation?

[henrebotha]

I challenge you to find documentation for, say, --enable-post-process-file.

[pixelshaded]

In the docs for the gradle plugin: https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator-gradle-plugin/README.adoc

To enable the file post-processing hook. This enables executing an external post-processor (usually a linter program). This only enables the post-processor. To define the post-processing command, define an environment variable such as LANG_POST_PROCESS_FILE (e.g. GO_POST_PROCESS_FILE, SCALA_POST_PROCESS_FILE). Please open an issue if your target generator does not support this functionality.

So this sounds very generator specific. Looking at the source code, just about every generator is looking for its own environment variable. Here is processOpts from the AbstractJavaCodegen.

        if (StringUtils.isEmpty(System.getenv("JAVA_POST_PROCESS_FILE"))) {
            LOGGER.info("Environment variable JAVA_POST_PROCESS_FILE not defined so the Java code may not be properly formatted. To define it, try 'export JAVA_POST_PROCESS_FILE=\"/usr/local/bin/clang-format -i\"' (Linux/Mac)");
            LOGGER.info("NOTE: To enable file post-processing, 'enablePostProcessFile' must be set to `true` (--enable-post-process-file for CLI).");
        }

So the source code confirms the convention described in the gradle plugin doc.

This took less than 30 min to track down. Id suggest forking/downloading the source code since it also contains all the .md files and you can do a text search across everything, docs and source code, to better understand what is happening. That's how I found this tidbit in the gradle plugin docs even though I never use gradle.

So yes, that particular option isn't documented well since everywhere else it pretty much repeats the name of what it is rather than going in to detail on how to use it. Sounds like a good candidate for a pull request. My question would be: did you have a need to understand this cli option? There is plenty of documentation about how to get things done with openAPI generator. What specific thing are you trying to accomplish that doesn't seem to exist in the docs?

[henrebotha]

Ok, so to find that, I'd have to guess that it would be referred to not as --enable-post-process-file, as per the actual CLI, but enablePostProcessFile. (I actually did grep for the CLI argument, and found nothing.) Further, I'd have to guess that a core CLI feature is actually documented in… a Gradle plugin? I don't even use Gradle. Why should I go there for core functionality?

This took less than 30 min to track down.

This is not a resounding success, it is an abject failure on the part of the docs.

My question would be: did you have a need to understand this cli option?

Obviously.

[pixelshaded]

Asking about a specific, poorly documented cli option is far more constructive than making a generalized FALSE statement that the tool has no proper documentation. The former is asking for specific help, or even pointing out a specific issue with docs. The latter is largely just a complaint without any details that serves absolutely no one.

[CoenWarmer]

I too came looking for documentation on --enable-post-process-file and find it a perfectly reasonable expectation that that can be found through the main documentation for the project, whether that is the main README.md or a documentation site.

Not denying anyone's efforts here, just stating there's room for improvement here.

[jimschubert]

Please follow community guidelines and be respectful and constructive.

There's always room for improvement in documentation, but opening issues containing only a description of:

There is no proper documentation for this tool anywhere.

Is neither constructive or respectful. I spent maybe 80% of my efforts on this project last year putting together the documentation site at https://openapi-generator.tech, making it easier for developers to find information about the tool through the CLI, putting together multiple example repositories, and driving the adoption of our Slack community specifically for simple questions/asks such as these.

Since we have a standard /docs folder and https://openapi-generator.tech is linked directly in the repository's description, I've changed the title of this issue to more clearly reflect the ask.