From: Alexis Laferrière Date: Fri, 29 May 2015 01:16:23 +0000 (-0400) Subject: lib: update doc to refer to the `serialize` annotation X-Git-Tag: v0.7.5~8^2~2 X-Git-Url: http://nitlanguage.org lib: update doc to refer to the `serialize` annotation Signed-off-by: Alexis Laferrière --- diff --git a/lib/android/bundle/bundle.nit b/lib/android/bundle/bundle.nit index fde88af..edb0c88 100644 --- a/lib/android/bundle/bundle.nit +++ b/lib/android/bundle/bundle.nit @@ -503,7 +503,7 @@ class Bundle # Retrieve an `Object` serialized via `[]=` function # Returns `null` if there's no serialized object corresponding to the given key # or if it's the wrong value type - # Make sure that the serialized object is `auto_serializable` or that it + # Make sure that the serialized object is `serialize` or that it # redefines the appropriate methods. Refer to `Serializable` documentation # for further details fun deserialize(key: String): nullable Object @@ -520,7 +520,7 @@ class Bundle # Retrieve an `Array` of `Object` serialized via `[]=` function # Returns `null` if there's no serialized `Array` corresponding to the given key # or if it's the wrong value type - # Make sure that the serialized objects are `auto_serializable` or that they + # Make sure that the serialized objects are `serialize` or that they # redefine the appropriate methods. Refer to `Serializable` documentation # for further details fun deserialize_array(key: String): nullable Array[nullable Object] diff --git a/lib/android/shared_preferences/shared_preferences_api10.nit b/lib/android/shared_preferences/shared_preferences_api10.nit index d4e71a8..ca3a2b9 100644 --- a/lib/android/shared_preferences/shared_preferences_api10.nit +++ b/lib/android/shared_preferences/shared_preferences_api10.nit @@ -390,7 +390,7 @@ class SharedPreferences # Retrieve an `Object` stored via `[]=` function # # Returns `null` if there's no serialized object corresponding to the given key - # Make sure that the serialized object is `auto_serializable` or that it redefines + # Make sure that the serialized object is `serialize` or that it redefines # the appropriate methods. Refer to `Serializable` documentation for further details fun [](key: String): nullable Object do diff --git a/lib/json/serialization.nit b/lib/json/serialization.nit index 4b7cb15..359acf5 100644 --- a/lib/json/serialization.nit +++ b/lib/json/serialization.nit @@ -39,7 +39,7 @@ # import json::serialization # # class Person -# auto_serializable +# serialize # # var name: String # var year_of_birth: Int diff --git a/lib/serialization/README.md b/lib/serialization/README.md index 4cbcf64..fb15108 100644 --- a/lib/serialization/README.md +++ b/lib/serialization/README.md @@ -1,11 +1,11 @@ # Abstract serialization services -The serialization services are centered around the `auto_serializable` annotation, +The serialization services are centered around the `serialize` annotation, the `Serializable` interface and the implementations of `Serializer` and `Deserializer`. -## The `auto_serializable` annotation +## The `serialize` annotation -A class annotated with `auto_serializable` identifies it as a subclass of Serializable and +A class annotated with `serialize` identifies it as a subclass of Serializable and triggers the generation of customized serialization and deserialization services. ~~~ @@ -13,7 +13,7 @@ import serialization # Simple serializable class identifying a human class Person - auto_serializable + serialize # First and last name var name: String @@ -31,19 +31,19 @@ By definition of a serializable class, an instance can be serialized to a stream The deserialized instance will not be the same instance, but they should be equal. So, in this case, we can compare both instances with `==` to test their equality. -Some conditions applies to the classes that can be annotated as `auto_serializable`. +Some conditions applies to the classes that can be annotated as `serialize`. All attributes of the class must be serializable, runtime errors will be raised when trying to serialize non-serializable attributes. In the class `Person`, all attributes are typed with classes the standards library. These common types are defined defined as serializable by this project. -The attributes could also be typed with user-defined `auto_serializable` +The attributes could also be typed with user-defined `serialize` classes or any other subclass of `Serializable`. ~~~ -# This `auto_serializable` class is composed of two `auto_serializable` attributes +# This `serialize` class is composed of two `serialize` attributes class Partnership - auto_serializable + serialize var partner_a: Person var partner_b: Person @@ -53,14 +53,14 @@ class Partnership end ~~~ -The `auto_serializable` applies only to the class definition, +The `serialize` applies only to the class definition, only attributes declared locally will be serialized. However, each definition of a class (a refinement or specialization) -can declare `auto_serializable`. +can declare `serialize`. ## Custom serializable classes -The annotation `auto_serializable` should be enough for most cases, +The annotation `serialize` should be enough for most cases, but in some cases you need more control over the serialization process. For more control, create a subclass to `Serializable` and redefine `core_serialize_to`. @@ -72,7 +72,7 @@ The method should only act on known class names, and call super otherwise. ### Example: the User class -The following example cannot use the `auto_serializable` annotations +The following example cannot use the `serialize` annotations because some of the arguments to the `User` class need special treatment: * The `name` attribute is perfectly normal, it can be serialized and deserialized @@ -160,7 +160,7 @@ information on the services to redefine. ## Serialization services -The `auto_serializable` annotation and the `Serializable` class are used on +The `serialize` annotation and the `Serializable` class are used on classes specific to the business domain. To write (and read) instances of these classes to a persistent format you must use implementations of `Serializer` and `Deserializer`. @@ -198,7 +198,7 @@ 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 `auto_serializable` annotation. + simply declare the `serialize` annotation. * A limitation of the Json parser prevents deserializing from files with more than one object. @@ -206,9 +206,9 @@ The serialization has some limitations: serialize a single object to each filesand use different instances of serializer and deserializer each time. -* The `auto_serializable` annotation does not handle very well +* The `serialize` annotation does not handle very well complex constructors. This could be improved in the compiler. - For now, you may prefer to use `auto_serializable` on simple classes, + 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. diff --git a/lib/serialization/serialization.nit b/lib/serialization/serialization.nit index 3ab8351..ca60d7a 100644 --- a/lib/serialization/serialization.nit +++ b/lib/serialization/serialization.nit @@ -16,7 +16,7 @@ # Abstract services to serialize Nit objects to different formats # -# This module declares the `auto_serializable` annotation to mark Nit classes as serializable. +# This module declares the `serialize` annotation to mark Nit classes as serializable. # For an introduction to this service, refer to the documentation of the `serialization` group. # This documentation provides more technical information on interesting entitie of this module. #