jakartaee / jakartaee/jsonb-api

JsonbTypeDeserializer and JsonbTypeSerialiser JavaDoc is misleading

Open
#89 4 comments 0 reactions 0 assignees View on GitHub
bug documentation
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.