Merge: lib/config: fix doc

[nit.git] / lib / serialization / README.md

diff --git a/lib/serialization/README.md b/lib/serialization/README.md
index ef8c445..3f6ac6c 100644 (file)
--- a/lib/serialization/README.md
+++ b/lib/serialization/README.md
@@ -103,6 +103,26 @@ The `noserialize` annotation mark an exception in a `serialize` module or class
   end
   ~~~
 
+## The `serialize_as` annotation
+
+By default, an attribute is identified in the serialization format by its Nit name.
+The `serialize_as` attribute changes this behavior and sets the name of an attribute in the serialization format.
+
+This annotation can be useful to change the name of an attribute to what is expected by a remote service.
+Or to use identifiers in the serialization format that are reserved keywords in Nit (like `class` and `type`).
+
+~~~
+class UserCredentials
+       serialize
+
+       # Rename to "username" in JSON for compatibility with remote service
+       var name: String is serialize_as "username"
+
+       # Rename to a shorter "ap" for a smaller JSON file
+       var avatar_path: String = "/somepath/"+name is lazy, serialize_as "ap"
+end
+~~~
+
 ## Custom serializable classes
 
 The annotation `serialize` should be enough for most cases,
@@ -214,7 +234,7 @@ The main implementations of these services are `JsonSerializer` and `JsonDeseria
 from the `json_serialization` module.
 
 ~~~
-import json_serialization
+import json
 import user_credentials
 
 # Data to be serialized and deserialized
@@ -240,22 +260,12 @@ assert couple == deserialize_couple
 
 The serialization has some limitations:
 
-* Not enough classes from the standard library are supported.
-  This only requires someone to actually code the support.
-  It should not be especially hard for most classes, some can
-  simply declare the `serialize` annotation.
-
-* A limitation of the Json parser prevents deserializing from files
+* A limitation of the JSON parser prevents deserializing from files
   with more than one object.
   This could be improved in the future, but for now you should
-  serialize a single object to each filesand use different instances of
+  serialize a single object to each files and use different instances of
   serializer and deserializer each time.
 
-* The `serialize` annotation does not handle very well
-  complex constructors. This could be improved in the compiler.
-  For now, you may prefer to use `serialize` on simple classes,
-  of by using custom `Serializable`.
-
 * The serialization uses only the short name of a class, not its qualified name.
   This will cause problem when different classes using the same name.
   This could be solved partially in the compiler and the library.
@@ -263,7 +273,7 @@ The serialization has some limitations:
   the different programs sharing the serialized data.
 
 * The serialization support in the compiler need some help to
-  deal with generic types. The solution is to use `nitserial`,
+  deal with generic types. A solution is to use `nitserial`,
   the next section explores this subject.
 
 ## Dealing with generic types