diff --git a/README.md b/README.md
index bcc6ebdc..ac3d8873 100644
--- a/README.md
+++ b/README.md
@@ -5,7 +5,7 @@ Gson can work with arbitrary Java objects including pre-existing objects that yo
There are a few open-source projects that can convert Java objects to JSON. However, most of them require that you place Java annotations in your classes; something that you can not do if you do not have access to the source-code. Most also do not fully support the use of Java Generics. Gson considers both of these as very important design goals.
*Gson Goals*
- * Provide simple toJson() and fromJson() methods to convert Java objects to JSON and vice-versa
+ * Provide simple `toJson()` and `fromJson()` methods to convert Java objects to JSON and vice-versa
* Allow pre-existing unmodifiable objects to be converted to and from JSON
* Extensive support of Java Generics
* Allow custom representations for objects
diff --git a/UserGuide.md b/UserGuide.md
index dbf9af6b..bd506f64 100644
--- a/UserGuide.md
+++ b/UserGuide.md
@@ -52,17 +52,17 @@ Gson can work with arbitrary Java objects including pre-existing objects that yo
Here are some metrics that we obtained on a desktop (dual opteron, 8GB RAM, 64-bit Ubuntu) running lots of other things along-with the tests. You can rerun these tests by using the class [PerformanceTest](http://code.google.com/p/google-gson/source/browse/trunk/gson/src/test/java/com/google/gson/metrics/PerformanceTest.java).
-* Strings: Deserialized strings of over 25MB without any problems (see disabled_testStringDeserializationPerformance method in PerformanceTest)
+* Strings: Deserialized strings of over 25MB without any problems (see `disabled_testStringDeserializationPerformance` method in `PerformanceTest`)
* Large collections:
-* Serialized a collection of 1.4 million objects (see disabled_testLargeCollectionSerialization method in PerformanceTest)
+* Serialized a collection of 1.4 million objects (see `disabled_testLargeCollectionSerialization` method in `PerformanceTest`)
-* Deserialized a collection of 87,000 objects (see disabled_testLargeCollectionDeserialization in PerformanceTest)
+* Deserialized a collection of 87,000 objects (see `disabled_testLargeCollectionDeserialization` in `PerformanceTest`)
* Gson 1.4 raised the deserialization limit for byte arrays and collection to over 11MB from 80KB.
-Note: Delete the disabled_ prefix to run these tests. We use this prefix to prevent running these tests every time we run junit tests.
+Note: Delete the `disabled_` prefix to run these tests. We use this prefix to prevent running these tests every time we run junit tests.
## Gson Users
@@ -211,8 +211,8 @@ Collection ints2 = gson.fromJson(json, collectionType);
ints2 is same as ints
```
-Fairly hideous: note how we define the type of collection
-Unfortunately, no way to get around this in Java
+Fairly hideous: note how we define the type of collection.
+Unfortunately, there is no way to get around this in Java.
#### Collections Limitations
@@ -220,11 +220,11 @@ Unfortunately, no way to get around this in Java
* Because there is no way for the user to indicate the type of the resulting object
* While deserializing, Collection must be of a specific generic type
-All of this makes sense, and is rarely a problem when following good Java coding practices
+All of this makes sense, and is rarely a problem when following good Java coding practices.
### Serializing and Deserializing Generic Types
-When you call `toJson(obj)`, Gson calls `obj.getClass()` to get information on the fields to serialize. Similarly, you can typically pass MyClass.class object in the fromJson(json, MyClass.class) method. This works fine if the object is a non-generic type. However, if the object is of a generic type, then the Generic type information is lost because of Java Type Erasure. Here is an example illustrating the point:
+When you call `toJson(obj)`, Gson calls `obj.getClass()` to get information on the fields to serialize. Similarly, you can typically pass `MyClass.class` object in the `fromJson(json, MyClass.class)` method. This works fine if the object is a non-generic type. However, if the object is of a generic type, then the Generic type information is lost because of Java Type Erasure. Here is an example illustrating the point:
```
class Foo {
T value;
@@ -236,9 +236,9 @@ gson.toJson(foo); // May not serialize foo.value correctly
gson.fromJson(json, foo.getClass()); // Fails to deserialize foo.value as Bar
```
-The above code fails to interpret value as type Bar because Gson invokes `list.getClass()` to get its class information, but this method returns a raw class, Foo.class. This means that Gson has no way of knowing that this is an object of type Foo, and not just plain Foo.
+The above code fails to interpret value as type Bar because Gson invokes `list.getClass()` to get its class information, but this method returns a raw class, `Foo.class`. This means that Gson has no way of knowing that this is an object of type `Foo`, and not just plain `Foo`.
-You can solve this problem by specifying the correct parameterized type for your generic type. You can do this by using the [TypeToken](http://google.github.io/gson/apidocs/com/google/gson/reflect/TypeToken.html) class.
+You can solve this problem by specifying the correct parameterized type for your generic type. You can do this by using the [`TypeToken`](http://google.github.io/gson/apidocs/com/google/gson/reflect/TypeToken.html) class.
```
Type fooType = new TypeToken>() {}.getType();
gson.toJson(foo, fooType);
@@ -348,22 +348,21 @@ Often you want to register a single handler for all generic types corresponding
* Essentially write out the id value
* Deserialization is very similar but not exactly the same
- * Need to call "new Id(Class, String)" which returns an instance of Id
+ * Need to call `new Id(Class, String)` which returns an instance of `Id`
-Gson supports registering a single handler for this. You can also register a specific handler for a specific generic type (say Id needed special handling).
-The Type parameter for the toJson and fromJson contains the generic type information to help you write a single handler for all generic types corresponding to the same raw type
+Gson supports registering a single handler for this. You can also register a specific handler for a specific generic type (say `Id` needed special handling).
+The `Type` parameter for the `toJson` and `fromJson` contains the generic type information to help you write a single handler for all generic types corresponding to the same raw type.
### Writing an Instance Creator
-While deserializing an Object, Gson needs to create a default instance of the class
-Well-behaved classes that are meant for serialization and deserialization should have a no-argument constructor
+While deserializing an Object, Gson needs to create a default instance of the class.
+Well-behaved classes that are meant for serialization and deserialization should have a no-argument constructor.
* Doesn't matter whether public or private
Typically, Instance Creators are needed when you are dealing with a library class that does NOT define a no-argument constructor
-**
-Instance Creator Example**
+**Instance Creator Example**
```
private class MoneyInstanceCreator implements InstanceCreator {
@@ -393,7 +392,7 @@ class MyListInstanceCreator implements InstanceCreator> {
}
}
```
-However, sometimes you do need to create instance based on the actual parameterized type. In this case, you can use the type parameter being passed to the createInstance method. Here is an example:
+However, sometimes you do need to create instance based on the actual parameterized type. In this case, you can use the type parameter being passed to the `createInstance` method. Here is an example:
```
public class Id {
private final Class classOfId;
@@ -413,15 +412,15 @@ class IdInstanceCreator implements InstanceCreator> {
}
```
-In the above example, an instance of the Id class can not be created without actually passing in the actual type for the parameterized type. We solve this problem by using the passed method parameter, type. The type object in this case is the Java parameterized type representation of Id where the actual instance should be bound to Id. Since Id class has just one parameterized type parameter, T, we use the zeroth element of the type array returned by getActualTypeArgument() which will hold Foo.class in this case.
+In the above example, an instance of the Id class can not be created without actually passing in the actual type for the parameterized type. We solve this problem by using the passed method parameter, `type`. The `type` object in this case is the Java parameterized type representation of `Id` where the actual instance should be bound to `Id`. Since `Id` class has just one parameterized type parameter, `T`, we use the zeroth element of the type array returned by `getActualTypeArgument()` which will hold `Foo.class` in this case.
### Compact Vs. Pretty Printing for JSON Output Format
The default JSON output that is provide by Gson is a compact JSON format. This means that there will not be any whitespace in the output JSON structure. Therefore, there will be no whitespace between field names and its value, object fields, and objects within arrays in the JSON output. As well, "null" fields will be ignored in the output (NOTE: null values will still be included in collections/arrays of objects). See the [Null Object Support](#TOC-Null-Object-Support) section for information on configure Gson to output all null values.
-If you like to use the Pretty Print feature, you must configure your `Gson` instance using the `GsonBuilder`. The `JsonFormatter` is not exposed through our public API, so the client is unable to configure the default print settings/margins for the JSON output. For now, we only provide a default JsonPrintFormatter that has default line length of 80 character, 2 character indentation, and 4 character right margin.
+If you like to use the Pretty Print feature, you must configure your `Gson` instance using the `GsonBuilder`. The `JsonFormatter` is not exposed through our public API, so the client is unable to configure the default print settings/margins for the JSON output. For now, we only provide a default `JsonPrintFormatter` that has default line length of 80 character, 2 character indentation, and 4 character right margin.
-The following is an example shows how to configure a `Gson` instance to use the default `JsonPrintFormatter` instead of the JsonCompactFormatter:
+The following is an example shows how to configure a `Gson` instance to use the default `JsonPrintFormatter` instead of the `JsonCompactFormatter`:
```
Gson gson = new GsonBuilder().setPrettyPrinting().create();
String jsonOutput = gson.toJson(someObject);
@@ -465,7 +464,7 @@ null
```
### Versioning Support
-Multiple versions of the same object can be maintained by using [@Since](http://code.google.com/p/google-gson/source/browse/trunk/gson/src/main/java/com/google/gson/annotations/Since.java "@Since") annotation. This annotation can be used on Classes, Fields and, in a future release, Methods. In order to leverage this feature, you must configure your Gson instance to ignore any field/object that is greater than some version number. If no version is set on the Gson instance then it will serialize and deserialize all fields and classes regardless of the version.
+Multiple versions of the same object can be maintained by using [@Since](http://code.google.com/p/google-gson/source/browse/trunk/gson/src/main/java/com/google/gson/annotations/Since.java "@Since") annotation. This annotation can be used on Classes, Fields and, in a future release, Methods. In order to leverage this feature, you must configure your `Gson` instance to ignore any field/object that is greater than some version number. If no version is set on the `Gson` instance then it will serialize and deserialize all fields and classes regardless of the version.
```
public class VersionedClass {
@Since(1.1) private final String newerField;
@@ -517,11 +516,11 @@ Gson gson = new GsonBuilder()
#### Gson's @Expose
-This feature provides a way where you can mark certain fields of your objects to be excluded for consideration for serialization and deserialization to JSON. To use this annotation, you must create Gson by using new GsonBuilder().excludeFieldsWithoutExposeAnnotation().create(). The Gson instance created will exclude all fields in a class that are not marked with `@Expose` annotation.
+This feature provides a way where you can mark certain fields of your objects to be excluded for consideration for serialization and deserialization to JSON. To use this annotation, you must create Gson by using `new GsonBuilder().excludeFieldsWithoutExposeAnnotation().create()`. The Gson instance created will exclude all fields in a class that are not marked with `@Expose` annotation.
#### User Defined Exclusion Strategies
-If the above mechanisms for excluding fields and class type do not work for you then you can always write your own exclusion strategy and plug it into Gson. See the [ExclusionStrategy](http://google-gson.googlecode.com/svn/trunk/gson/docs/javadocs/com/google/gson/ExclusionStrategy.html) JavaDoc for more information.
+If the above mechanisms for excluding fields and class type do not work for you then you can always write your own exclusion strategy and plug it into Gson. See the [`ExclusionStrategy`](http://google-gson.googlecode.com/svn/trunk/gson/docs/javadocs/com/google/gson/ExclusionStrategy.html) JavaDoc for more information.
The following example shows how to exclude fields marked with a specific "@Foo" annotation and excludes top-level types (or declared field type) of class String.
```
@@ -575,7 +574,7 @@ The following example shows how to exclude fields marked with a specific "@Foo"
```
### JSON Field Naming Support
-Gson supports some pre-defined field naming policies to convert the standard Java field names (i.e. camel cased names starting with lower case --- "sampleFieldNameInJava") to a Json field name (i.e. sample_field_name_in_java or SampleFieldNameInJava). See the [FieldNamingPolicy](http://google.github.io/gson/apidocs/com/google/gson/FieldNamingPolicy.html) class for information on the pre-defined naming policies.
+Gson supports some pre-defined field naming policies to convert the standard Java field names (i.e., camel cased names starting with lower case --- `sampleFieldNameInJava`) to a Json field name (i.e., `sample_field_name_in_java` or `SampleFieldNameInJava`). See the [FieldNamingPolicy](http://google.github.io/gson/apidocs/com/google/gson/FieldNamingPolicy.html) class for information on the pre-defined naming policies.
It also has an annotation based strategy to allows clients to define custom names on a per field basis. Note, that the annotation based strategy has field name validation which will raise "Runtime" exceptions if an invalid field name is provided as the annotation value.