glideapps / glideapps/quicktype

javadoc warning: missing @return annotation

Open
#1,793 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
13.9k
Forks
1.2k
Avg merge
8h 53m
Merged PRs (30d)
369

Description

**problem**

Let's assume this is written somewhere in a json-schema File:
```
"Person":{
"name": {
"description": "the name of a person",
"type": "string",
}
}
```
When generating java classes from the json-schema then a class Person is generated with the following getter for the property "name" (note that the description is added as a comment above the getter):
```
/**
* the name of a person
*/
@JsonProperty("name")
public String getName() { return name; }
```

When running the javadoc task from the gradle java plugin the following warning occurs:
```
warning: no @return
public String getName() { return name; }
^
```
That is because when adding a comment like quicktype does above a function javadoc assumes this is documentation and then requires a @return-Annotation like:
```
/**
* @return the name of a person
*/
@JsonProperty("name")
public String getName() { return name; }
```

**solution proposal**

- Add an additional cli-flag for java (e.g. -[no-]description-block) which controls wether the function `public emitDescriptionBlock(lines: Sourcelike[])` in `Java.ts` is called or not.
- or add a cli-flag for java (e.g. -[no-]return-annotation) which controls wether an @return-Annotation is added to the desciption-block

I would like to discuss this with you :)

P.S.: I would agree to implement a solution myself

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.