Fix and add the documentation for Built-in Serializers and Deserializers #2441

Lalitha333 · 2023-07-21T15:46:19Z

Purpose

This PR has updates to the documentation on built-in serializers and deserializers with examples and types supported w.r.t an issue opened for missing/incorrect documentation.
"Closes #620" -->

Description

Updated the Built-in Serializers and deserializers section under UserGuide
#620

Checklist

New code follows the Google Java Style Guide
If necessary, new public API validates arguments, for example rejects null
New public API has Javadoc
- Javadoc uses @since $next-version$
  ( $next-version$ is a special placeholder which is automatically replaced during release)
If necessary, new unit tests have been added
- Assertions in unit tests use Truth, see existing tests
- No JUnit 3 features are used (such as extending class TestCase)
- If this pull request fixes a bug, a new test was added for a situation which failed previously and is now fixed
mvn clean verify javadoc:jar passes without errors

google-cla · 2023-07-21T15:46:23Z

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

Marcono1234

Thanks! This looks really useful, and is definitely better than only referring the user to the internal implementation details.

If you think this resolves the GitHub issue you mentioned in the description, could you please edit the description to contain "Closes #..."; this way GitHub automatically recognizes this.

A few of my comments below might be nit-picky, feel free to consider them as suggestions, you don't have to follow them strictly. However, it looks like in some cases you also described the serialized output incorrectly.

Note that I am not a direct project member, and they might think differently.

Marcono1234 · 2023-07-21T20:42:07Z

UserGuide.md

+For example, suppose you have a Java class `Person`:
+
+```java
+public class Person {
+private String name;
+private int age;
+// constructors, getters, setters, etc.
+}
+```
+You can serialize an instance of `Person` to JSON using Gson like this:
+
+```java
+Person person = new Person("John Doe", 30);
+Gson gson = new Gson();
+String json = gson.toJson(person);
+```
+The output JSON would be: `{"name":"John Doe","age":30}`.
+
+And you can deserialize the JSON back to a `Person` object like this:
+
+```java
+String json = "{\"name\":\"Jane Smith\",\"age\":25}";
+Person person = gson.fromJson(json, Person.class);
+```
+The `gson.fromJson()` method uses the built-in deserializers to convert the JSON back into a `Person` object.
+
+Gson also allows you to customize serialization and deserialization by providing your own custom serializers and deserializers for specific types if needed.


Not sure if this section here with the Person example is needed since there are already multiple examples for object serialization above, and also this is not directly about the built-in serializers.

Marcono1234 · 2023-07-21T20:44:15Z

UserGuide.md

+Gson also allows you to customize serialization and deserialization by providing your own custom serializers and deserializers for specific types if needed.
+
+Below is a list of some of the classes supported by Gson's built-in serializers and deserializers:
+


Is there a specific reason why you chose to use a numbered list here? A numbered list suggests some kind of ordering or priorities and I am not sure if that is correct here, or needed. Maybe a regular unordered list would be better?

@Marcono1234 Sure, changed to unordered list.

@Lalitha333, just to clarify, you are still working on these changes, right? Or did you forget to push the commits?

@Marcono1234 Sorry for the delay, yes I’m going to push the changes as per review comments.

Marcono1234 · 2023-07-21T20:46:06Z

UserGuide.md

+Below is a list of some of the classes supported by Gson's built-in serializers and deserializers:
+
+1. Primitive Types:
+    * `int, Integer, long, Long, float, Float, double, Double, boolean, Boolean, char, Character, byte, Byte, short, Short.`


Could you please format each type separately as code, e.g. int, long, ...
Having this formatted as one single code line looks a bit weird.

Also, maybe omit the wrapper types and just add something like "(and their wrappers)" at the end to make it easier to read.

Marcono1234 · 2023-07-21T20:48:28Z

UserGuide.md

+    * java.util.List: List of objects.
+    * java.util.Set: Set of objects.
+    * java.util.Map: Map of key-value pairs.


Maybe instead of listing List and Set separately, write something like the following because Gson actually supports any Collection:

java.util.Collection: Collection of objects, and collection subtypes such as List or Set.

And also in general maybe format the class names here and below as code, e.g. "java.util.Map" instead of just "java.util.Map".

Marcono1234 · 2023-07-21T20:49:37Z

UserGuide.md

+5. BigInteger and BigDecimal:
+    * java.math.BigInteger: Serialized as a string.
+    * java.math.BigDecimal: Serialized as a string.
+6. Enumerations:


Maybe call it "Enum Types" in the header here as well, that might be clearer than "Enumerations".

Marcono1234 · 2023-07-21T21:00:46Z

UserGuide.md

+7. Optional:
+    * java.util.Optional: Serializes the value if present; otherwise, it serializes as null.
+8. Custom Objects:
+    * Gson can automatically serialize and deserialize custom Java objects using reflection. It serializes the non-static, non-transient fields of an object. 


Suggested change

* Gson can automatically serialize and deserialize custom Java objects using reflection. It serializes the non-static, non-transient fields of an object.

* Gson can automatically serialize and deserialize custom Java objects using reflection. By default, it serializes the non-static, non-transient fields of an object.

(Because this can be customized)

Marcono1234 · 2023-07-21T21:01:47Z

UserGuide.md

+8. Custom Objects:
+    * Gson can automatically serialize and deserialize custom Java objects using reflection. It serializes the non-static, non-transient fields of an object. 
+
+It's important to note that Gson's built-in serializers and deserializers can handle nested objects and collections of objects as well. If a class is not supported by Gson's default behavior, you can provide custom serialization and deserialization logic using Gson's JsonSerializer and JsonDeserializer interfaces.


Maybe this should rather recommend TypeAdapter since the documentation for JsonSerializer and JsonDeserializer also recommend TypeAdapter for performance reasons.

Suggested change

It's important to note that Gson's built-in serializers and deserializers can handle nested objects and collections of objects as well. If a class is not supported by Gson's default behavior, you can provide custom serialization and deserialization logic using Gson's JsonSerializer and JsonDeserializer interfaces.

It's important to note that Gson's built-in serializers and deserializers can handle nested objects and collections of objects as well. If a class is not supported by Gson's default behavior, you can provide custom serialization and deserialization logic using Gson's `TypeAdapter` class.

Or maybe even omit this sentence because the section "Custom Serialization and Deserialization" is directly below this.

Marcono1234 · 2023-07-21T21:04:23Z

UserGuide.md

+    * java.util.List: List of objects.
+    * java.util.Set: Set of objects.
+    * java.util.Map: Map of key-value pairs.
+4. Date and Time:


Maybe this should also refer to GsonBuilder.setDateFormat(...)

Marcono1234 · 2023-07-21T21:12:31Z

UserGuide.md


-* `java.net.URL` to match it with strings like `"https://github.com/google/gson/"`
-* `java.net.URI` to match it with strings like `"/google/gson/"`


Maybe it would be good to include URL and URI in the list below again with a description like "Serialized as their string representation" or similar, since these types might also be somewhat common.

Marcono1234 · 2023-07-21T21:18:42Z

UserGuide.md

+8. Custom Objects:
+    * Gson can automatically serialize and deserialize custom Java objects using reflection. It serializes the non-static, non-transient fields of an object. 
+
+It's important to note that Gson's built-in serializers and deserializers can handle nested objects and collections of objects as well. If a class is not supported by Gson's default behavior, you can provide custom serialization and deserialization logic using Gson's JsonSerializer and JsonDeserializer interfaces.

 For many more, see the internal class [`TypeAdapters`](gson/src/main/java/com/google/gson/internal/bind/TypeAdapters.java).


Maybe reword this a bit to give a bit more context, for example:

Suggested change

For many more, see the internal class [`TypeAdapters`](gson/src/main/java/com/google/gson/internal/bind/TypeAdapters.java).

For more of the built-in serializers and deserializers, see the internal class [`TypeAdapters`](gson/src/main/java/com/google/gson/internal/bind/TypeAdapters.java).

Marcono1234 · 2023-08-13T00:33:11Z

Thanks for your changes! Do you want to address some or all of the other review comments as well?

Lalitha333 · 2023-08-21T15:04:52Z

Thanks for your changes! Do you want to address some or all of the other review comments as well?

I believe I made all the requested changes. Please let me know if I have missed any.

Marcono1234 · 2023-08-22T19:27:51Z

UserGuide.md

+    * `java.util.Collection`: Collection of objects, and collection subtypes such as:
+      * `java.util.List`: List of objects.
+      * `java.util.Set`: Set of objects.
+      * `java.util.Map`: Map of key-value pairs.


Should probably unindent this by one level because Map is not a subtype of Collection

Suggested change

* `java.util.Map`: Map of key-value pairs.

* `java.util.Map`: Map of key-value pairs.

Marcono1234 · 2023-08-22T19:32:41Z

@Lalitha333, yes there are a few unresolved points (I also just added a new single comment about your follow-up commit); see the GitHub documentation for how you can browse them.

If you addressed a comment, feel free to mark it as "resolved". Also, in case you don't want to address a comment, it might be good if you could write a short reply explaining this, so it is clear that you did not accidentally marked it as "resolved".

Fix the documentation for Built-in Serializers and Deserializers

2e65849

Marcono1234 reviewed Jul 21, 2023

View reviewed changes

update as per review suggestions

bfd70cc

Marcono1234 reviewed Aug 22, 2023

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix and add the documentation for Built-in Serializers and Deserializers #2441

Fix and add the documentation for Built-in Serializers and Deserializers #2441

Lalitha333 commented Jul 21, 2023 •

edited

google-cla bot commented Jul 21, 2023

Marcono1234 left a comment •

edited

Marcono1234 Jul 21, 2023

Marcono1234 Jul 21, 2023 •

edited

Lalitha333 Jul 24, 2023

Marcono1234 Jul 29, 2023

Lalitha333 Jul 29, 2023 •

edited

Marcono1234 Jul 21, 2023

Marcono1234 Jul 21, 2023 •

edited

Marcono1234 Jul 21, 2023

Marcono1234 Jul 21, 2023

Marcono1234 Jul 21, 2023

Marcono1234 Jul 21, 2023

Marcono1234 Jul 21, 2023

Marcono1234 Jul 21, 2023

Marcono1234 commented Aug 13, 2023

Lalitha333 commented Aug 21, 2023

Marcono1234 Aug 22, 2023

Marcono1234 commented Aug 22, 2023

		Gson also allows you to customize serialization and deserialization by providing your own custom serializers and deserializers for specific types if needed.

		Below is a list of some of the classes supported by Gson's built-in serializers and deserializers:

	* Gson can automatically serialize and deserialize custom Java objects using reflection. It serializes the non-static, non-transient fields of an object.
	* Gson can automatically serialize and deserialize custom Java objects using reflection. By default, it serializes the non-static, non-transient fields of an object.

	It's important to note that Gson's built-in serializers and deserializers can handle nested objects and collections of objects as well. If a class is not supported by Gson's default behavior, you can provide custom serialization and deserialization logic using Gson's JsonSerializer and JsonDeserializer interfaces.
	It's important to note that Gson's built-in serializers and deserializers can handle nested objects and collections of objects as well. If a class is not supported by Gson's default behavior, you can provide custom serialization and deserialization logic using Gson's `TypeAdapter` class.


		* `java.net.URL` to match it with strings like `"https://github.com/google/gson/"`
		* `java.net.URI` to match it with strings like `"/google/gson/"`

	For many more, see the internal class [`TypeAdapters`](gson/src/main/java/com/google/gson/internal/bind/TypeAdapters.java).
	For more of the built-in serializers and deserializers, see the internal class [`TypeAdapters`](gson/src/main/java/com/google/gson/internal/bind/TypeAdapters.java).

	* `java.util.Map`: Map of key-value pairs.
	* `java.util.Map`: Map of key-value pairs.

Fix and add the documentation for Built-in Serializers and Deserializers #2441

Are you sure you want to change the base?

Fix and add the documentation for Built-in Serializers and Deserializers #2441

Conversation

Lalitha333 commented Jul 21, 2023 • edited

Purpose

Description

Checklist

google-cla bot commented Jul 21, 2023

Marcono1234 left a comment • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Marcono1234 Jul 21, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Lalitha333 Jul 29, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Marcono1234 Jul 21, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Marcono1234 commented Aug 13, 2023

Lalitha333 commented Aug 21, 2023

Choose a reason for hiding this comment

Marcono1234 commented Aug 22, 2023

Lalitha333 commented Jul 21, 2023 •

edited

Marcono1234 left a comment •

edited

Marcono1234 Jul 21, 2023 •

edited

Lalitha333 Jul 29, 2023 •

edited

Marcono1234 Jul 21, 2023 •

edited