jakartaee / jakartaee/jsonb-api
JsonbTypeDeserializer and JsonbTypeSerialiser JavaDoc is misleading
- Dominant language
- Java
- Stars
- 95
- Forks
- 41
- Avg merge
- 1d 6h
- Merged PRs (30d)
- 35
Description
JsonbTypeDeserializer and JsonbTypeSerializer JavaDoc describes that the annotations are meant to be applied to 'fields and properties' (ie setter/getter).
https://github.com/eclipse-ee4j/jsonb-api/blob/master/api/src/main/java/javax/json/bind/annotation/JsonbTypeSerializer.java#L27
https://github.com/eclipse-ee4j/jsonb-api/blob/master/api/src/main/java/javax/json/bind/annotation/JsonbTypeDeserializer.java#L28
But further down it notes that it also can be applied to types!
These are really two different models. Which one do we want to support? Or both?
a.)
```
@JsonbTypeDeserializer(StudentDeserializer.class)
public class Student {
...
}
```
or
b.)
```
public class Student {...}
public class StudyBook {
@JsonbTypeDeserializer(StudentDeserializer.class)
private Student ownedBy;
```
In case we want to support both cases we should define that b.) wins over a.
Plus the spec is also not clear. In 4.7.2:
```
There are two ways how to register JsonbSerializer/JsonbDeserializer:
1. Using JsonbConfig::withSerializers/ JsonbConfig::withDeserializers method;
2. Annotating a type with JsonbSerializer/JsonbDeserializer annotation.
```
First, JsonbSerializer/JsonbDeserializer are _not* annotations. Did we mean @JsonbTypeDeserializer there? Second, 'annotating a type' supports the interpretation of case a.) and contradicts the first JavaDoc sentence in the anntations.
Btw, the same error is also being made in the JavaDoc ('The @JsonbSerializer annotation can be used with the following program elements'). This also should be JsonbTypeSerializer, etc.
Contributor guide
Research direction
Review api/src/main/java/javax/json/bind/annotation/JsonbTypeSerializer.java and JsonbTypeDeserializer.java alongside specification section 4.7.2. Resolve whether type and member annotations are both supported and which takes precedence, then update the referenced JavaDoc and specification wording so the supported model is consistent.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100