Skip to content

Clean up Javadoc warning when building the project #63

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wing328 opened this issue May 16, 2018 · 5 comments
Closed

Clean up Javadoc warning when building the project #63

wing328 opened this issue May 16, 2018 · 5 comments

Comments

@wing328
Copy link
Member

wing328 commented May 16, 2018

Description

File a PR to clean up the Javadoc warnings when for example building openapi-generator-online:

14 warnings
[WARNING] Javadoc Warnings
[WARNING] /Users/williamcheng/Code/3.0/openapi-generator/modules/openapi-generator-online/src/main/java/org/openapitools/codegen/online/api/GenApiDelegate.java:47: warning: no @return
[WARNING] default ResponseEntity<List<String>> clientOptions() {
[WARNING] ^
[WARNING] /Users/williamcheng/Code/3.0/openapi-generator/modules/openapi-generator-online/src/main/java/org/openapitools/codegen/online/api/GenApiDelegate.java:63: warning: no @param for fileId
[WARNING] default ResponseEntity<Resource> downloadFile(String  fileId) {
[WARNING] ^
[WARNING] /Users/williamcheng/Code/3.0/openapi-generator/modules/openapi-generator-online/src/main/java/org/openapitools/codegen/online/api/GenApiDelegate.java:63: warning: no @return
[WARNING] default ResponseEntity<Resource> downloadFile(String  fileId) {
[WARNING] ^
[WARNING] /Users/williamcheng/Code/3.0/openapi-generator/modules/openapi-generator-online/src/main/java/org/openapitools/codegen/online/api/GenApiDelegate.java:71: warning: no @param for language
[WARNING] default ResponseEntity<ResponseCode> generateClient( String  language,
[WARNING] ^
[WARNING] /Users/williamcheng/Code/3.0/openapi-generator/modules/openapi-generator-online/src/main/java/org/openapitools/codegen/online/api/GenApiDelegate.java:71: warning: no @param for generatorInput
[WARNING] default ResponseEntity<ResponseCode> generateClient( String  language,
[WARNING] ^
[WARNING] /Users/williamcheng/Code/3.0/openapi-generator/modules/openapi-generator-online/src/main/java/org/openapitools/codegen/online/api/GenApiDelegate.java:71: warning: no @return
[WARNING] default ResponseEntity<ResponseCode> generateClient( String  language,
[WARNING] ^
[WARNING] /Users/williamcheng/Code/3.0/openapi-generator/modules/openapi-generator-online/src/main/java/org/openapitools/codegen/online/api/GenApiDelegate.java:88: warning: no @param for framework
[WARNING] default ResponseEntity<ResponseCode> generateServerForLanguage( String  framework,
[WARNING] ^
[WARNING] /Users/williamcheng/Code/3.0/openapi-generator/modules/openapi-generator-online/src/main/java/org/openapitools/codegen/online/api/GenApiDelegate.java:88: warning: no @param for generatorInput
[WARNING] default ResponseEntity<ResponseCode> generateServerForLanguage( String  framework,
[WARNING] ^
[WARNING] /Users/williamcheng/Code/3.0/openapi-generator/modules/openapi-generator-online/src/main/java/org/openapitools/codegen/online/api/GenApiDelegate.java:88: warning: no @return
[WARNING] default ResponseEntity<ResponseCode> generateServerForLanguage( String  framework,
[WARNING] ^
[WARNING] /Users/williamcheng/Code/3.0/openapi-generator/modules/openapi-generator-online/src/main/java/org/openapitools/codegen/online/api/GenApiDelegate.java:105: warning: no @param for language
[WARNING] default ResponseEntity<Map<String, CliOption>> getClientOptions(String  language) {
[WARNING] ^
[WARNING] /Users/williamcheng/Code/3.0/openapi-generator/modules/openapi-generator-online/src/main/java/org/openapitools/codegen/online/api/GenApiDelegate.java:105: warning: no @return
[WARNING] default ResponseEntity<Map<String, CliOption>> getClientOptions(String  language) {
[WARNING] ^
[WARNING] /Users/williamcheng/Code/3.0/openapi-generator/modules/openapi-generator-online/src/main/java/org/openapitools/codegen/online/api/GenApiDelegate.java:113: warning: no @param for framework
[WARNING] default ResponseEntity<Map<String, CliOption>> getServerOptions( String  framework) {
[WARNING] ^
[WARNING] /Users/williamcheng/Code/3.0/openapi-generator/modules/openapi-generator-online/src/main/java/org/openapitools/codegen/online/api/GenApiDelegate.java:113: warning: no @return
[WARNING] default ResponseEntity<Map<String, CliOption>> getServerOptions( String  framework) {
[WARNING] ^
[WARNING] /Users/williamcheng/Code/3.0/openapi-generator/modules/openapi-generator-online/src/main/java/org/openapitools/codegen/online/api/GenApiDelegate.java:121: warning: no @return
[WARNING] default ResponseEntity<List<String>> serverOptions() {
[WARNING] ^

openapi-generator version

Latest master

Steps to reproduce

mvn clean package

Suggest a fix/enhancement

If anyone wants to work on this, please reply to let us know.

@jmini
Copy link
Member

jmini commented May 16, 2018

I think that this also apply to other modules, we have some javadoc that is not correct in our code.

@wing328 wing328 changed the title Clean up Javadoc warning when building openapi-generator-online Clean up Javadoc warning when building the project May 16, 2018
@wing328
Copy link
Member Author

wing328 commented May 16, 2018

@jmini I've updated the subject and the details

@jmini
Copy link
Member

jmini commented May 17, 2018

In the main openapi-generator module:

8 warnings
[WARNING] Javadoc Warnings
[WARNING] ___/openapi-generator/modules/openapi-generator/src/main/java/org/openapitools/codegen/DefaultCodegen.java:3980: warning: no description for @param
[WARNING] * @param openAPI
[WARNING] ^
[WARNING] ___/openapi-generator/modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/URLPathUtils.java:75: warning: no description for @param
[WARNING] * @param url
[WARNING] ^
[WARNING] ___/openapi-generator/modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/URLPathUtils.java:77: warning: no description for @return
[WARNING] * @return
[WARNING] ^
[WARNING] ___/openapi-generator/modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/URLPathUtils.java:85: warning: no description for @param
[WARNING] * @param url
[WARNING] ^
[WARNING] ___/openapi-generator/modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/URLPathUtils.java:87: warning: no description for @return
[WARNING] * @return
[WARNING] ^
[WARNING] ___/openapi-generator/modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/URLPathUtils.java:99: warning: no description for @param
[WARNING] * @param url
[WARNING] ^
[WARNING] ___/openapi-generator/modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/URLPathUtils.java:113: warning: no description for @param
[WARNING] * @param url
[WARNING] ^
[WARNING] ___/openapi-generator/modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/URLPathUtils.java:127: warning: no description for @param
[WARNING] * @param openAPI
[WARNING] ^

@jimschubert
Copy link
Member

@wing328 @jmini I've updated javadoc in GenApiDelegate in #140.

There are four remaining in the entire repo after my PR, but it sounded like Jeremie may have accounted for this in another PR:

[WARNING] Javadoc Warnings
[WARNING] /Users/jim/projects/openapi-generator/modules/openapi-generator/src/main/java/org/openapitools/codegen/CodegenProperty.java:130: warning: no @return
[WARNING] public String getDatatype() {
[WARNING] ^
[WARNING] /Users/jim/projects/openapi-generator/modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/ModelUtils.java:347: warning: no description for @param
[WARNING] * @param openAPI
[WARNING] ^
[WARNING] /Users/jim/projects/openapi-generator/modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/ModelUtils.java:376: warning: no description for @param
[WARNING] * @param openAPI
[WARNING] ^
[WARNING] /Users/jim/projects/openapi-generator/modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/ModelUtils.java:401: warning: no description for @param
[WARNING] * @param openAPI
[WARNING] ^

I think in the other, he mentioned ModelUtils. There's also CodegenProperty missing a return doc in the above.

@jmini
Copy link
Member

jmini commented May 24, 2018

I have opened #143 to fix the last issue.


Maybe we can now configure the maven build to fail on javadoc warnings? Or maybe also something we can catch during static analysis with Sonarqube (see #33).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants