Add JavaDoc to 'Json' classes #12559
Conversation
sbabcoc
force-pushed
the
pr/add-json-api-javadoc
branch
from
1277596
to
f3eed8d
Compare
| * <li>Classes that declare a {@code toJson()} method that returns primitives and collections.</li> | ||
| * </ul> | ||
| * </li> | ||
| * <li>Build-in deserialization of primitives and collections.</li> |
| * <li>Build-in deserialization of primitives and collections.</li> | ||
| * <li>Facilities to deserialize custom data types: | ||
| * <ul> | ||
| * <li>Classes that declare setter methods that adhere to the {@code JavaBean} specification.</li> |
There was a problem hiding this comment.
Probably worth pointing out that using the javabean spec makes instances mutable. The only way to get immutable instances is to use the fromJson method
There was a problem hiding this comment.
I added a note to this effect.
| * <li>Facilities to deserialize custom data types: | ||
| * <ul> | ||
| * <li>Classes that declare setter methods that adhere to the {@code JavaBean} specification.</li> | ||
| * <li>Classes that declare a {@code fromJson(JsonInput)} method.</li> |
There was a problem hiding this comment.
Can also use a fromJson(primitive) method if needed, which makes it easier to have "tiny types"
There was a problem hiding this comment.
I added this, and I also noted the potential for producing immutable objects. I wasn't sure about how to document "tiny types", though.
| * </li> | ||
| * </ul> | ||
| * | ||
| * The <b>Json</b> API also handles Selenium {@link org.openqa.selenium.Capabilities Capabilities} objects: |
There was a problem hiding this comment.
No need to point this out. The Capabilities interface as an asMap method, and that's used for serialising to json. There's no magic :)
There was a problem hiding this comment.
I removed this bit.
| * provide a {@code toJson()} method for the <b>Json</b> API to use for serialization. This is especially beneficial | ||
| * for objects that contain transient properties that should be omitted from the JSON output. | ||
| * <p> | ||
| * You can deserialize objects for which no explicit coercer has been defined via the <b>ObjectCoercer</b>. Note |
There was a problem hiding this comment.
The entry points for users of the JSON package are all in the Json class, though people might need to interact with a JsonInput. We shouldn't be encouraging people to look at the coercers.
The right thing to do is to use Json.toType(), which because of its funky signature will attempt to return the right type of object. You can use a TypeToken to coerce to novel types. eg Set<String> strings = Json.toType(input, new TypeToken<Set<String>>(){}.getType())
There was a problem hiding this comment.
I revised this sentence to eliminate the overt reference to ObjectCoercer. I still need to introduce the concept of TypeToken specifications.
| public class Json { | ||
| /** This constant declares the value of the {@code Content-Type} |
There was a problem hiding this comment.
Javadoc will know this is a constant anyway. You can just say "The value of the {@code Content-Type} headers of...."
| public static final String JSON_UTF_8 = "application/json; charset=utf-8"; | ||
|
|
||
| /** This constant specifies deserializing as {@code List<Map<String, Object>} */ |
There was a problem hiding this comment.
Same applies here and elsewhere: we don't need to tell people a constant is a constant
| import java.lang.reflect.Type; | ||
|
|
||
| /** | ||
| * This enumeration is used to specify the strategy used to assign values during deserialization. |
There was a problem hiding this comment.
There's no need to tell people this is an enum, so you can start the comment with "Used to specify...."
sbabcoc
force-pushed
the
pr/add-json-api-javadoc
branch
3 times, most recently
from
4a3fe16
to
10487f5
Compare
sbabcoc
force-pushed
the
pr/add-json-api-javadoc
branch
from
10487f5
to
e700f59
Compare
sbabcoc
force-pushed
the
pr/add-json-api-javadoc
branch
from
e700f59
to
741b7a1
Compare
…selenium into pr/add-json-api-javadoc
|
Was this a duplicated PR? |
|
I believe this is a duplicate of #12584 |
Thanks for contributing to Selenium!
A PR well described will help maintainers to quickly review and merge it
Before submitting your PR, please check our contributing guidelines.
Avoid large PRs, help reviewers by making them as simple and short as possible.
Description
In this PR, I'm adding JavaDoc headers to the classes and methods of Selenium's Json API.
Motivation and Context
The Selenium Json API is a very useful built-in mechanism for consuming and producing JSON representations of Java objects. This facility can be very useful, especially when interacting with GraphQL web service endpoints, but the lack of documentation can result in considerable confusion.
This PR adds JavaDoc headers to classes, methods, and defined constants to assist folks in using the Selenium Json API in their own code.
Types of changes
Checklist