improve doc

README.md

@@ -341,7 +341,7 @@ public class Yaml.Example : Yaml.Object
 {
     static construct
     {
-        Yaml.Object.register.add_type (
+        Yaml.Register.add_type (
             typeof (Yaml.Example),       // owned type
             typeof (Yaml.ExampleStruct), // property type
             typeof (Gee.ArrayList)       // property type
@@ -421,10 +421,7 @@ Example of implementation from `src/vala/Pluie/Yaml.Example.vala` :
         // non Yaml.Object type & registered type
         if (node == null) {
             if (type == typeof (Yaml.ExampleStruct)) {
-                node = new Yaml.Mapping (null, name);
+                node = this.type_struct.to_yaml_node (name);
-                new Yaml.Mapping.with_scalar (node, "red"  , this.type_struct.red.to_string ());
-                new Yaml.Mapping.with_scalar (node, "green", this.type_struct.green.to_string ());
-                new Yaml.Mapping.with_scalar (node, "blue" , this.type_struct.blue.to_string ());
             }
             else if (type == typeof (Gee.ArrayList)) {
                 node = new Yaml.Sequence (null, name);
@@ -437,6 +434,10 @@ Example of implementation from `src/vala/Pluie/Yaml.Example.vala` :
     }
 ```
 
+### Serialize/Deserialize
+
+
+
 -------------------
 
 ### more samples
@@ -454,6 +455,8 @@ see samples files in ./samples directory
 * ~~add docker image~~
 * ~~transform Yaml.Node nodes to Yaml.Object objects~~
 * ~~transform Yaml.Object objects to Yaml.Node nodes~~
+* ~~dumper~~
+* ~~serialize/deserialize~~
 * manage tag directives & tag (partially done)
 * improve doc
-* dumper
+

samples/yaml-dump.vala

@@ -49,24 +49,15 @@ int main (string[] args)
         
         of.action("Yaml.Node", "to_yaml_string");
         string yaml = root.to_yaml_string ();
+        string genpath = "./tag-generated.yml";
         try {
-            string genpath = "./tag-generated.yml";
+            var writter = new Io.Writter (genpath, true);
-            // an output file in the current working directory
-            var file = File.new_for_path (genpath);
-            // delete if file already exists
-            if (file.query_exists ()) {
-                file.delete ();
-            }
-            var dos = new DataOutputStream (file.create (FileCreateFlags.REPLACE_DESTINATION));
-            uint8[] data = yaml.data;
             long written = 0;
-            while (written < data.length) { 
+            writter.write (yaml.data, out written);
-                // sum of the bytes of 'text' that already have been written to the stream
-                written += dos.write (data[written:data.length]);
-            }
             of.echo ("write %ld bytes in `%s`".printf ((long) written, genpath));
             Yaml.Dumper.show_yaml_string (root, true, true, true);
-        } catch (Error e) {
+        }
+        catch (Error e) {
             stderr.printf ("%s\n", e.message);
             return 1;
         }

samples/yaml-serialize.vala

@@ -96,15 +96,11 @@ int main (string[] args)
         for (var i = 0; i < zdata.length; i++) {
             print ("%02x", zdata[i]);
         }
-        of.echo ("");
         of.action ("Deserialize zdata from", obj.yaml_name);
-        message ("*");
         root = Yaml.deserialize (zdata);
-        message ("*");
         root.display_childs ();
         of.action ("Yaml build first child", obj.yaml_name);
         obj  = (Yaml.Example) Yaml.Builder.from_node (root.first ());
-        message ("*");
         test_object (obj);
 
     }

src/vala/Pluie/Io.InputChunkStream.vala

@@ -29,6 +29,10 @@
  */
 
 using GLib;
+
+/**
+ * basic class to read file by chunk
+ */
 class Pluie.Io.InputChunkStream : Object
 {
     protected ulong      chunk_index;
@@ -37,6 +41,11 @@ class Pluie.Io.InputChunkStream : Object
     protected uint8[]    buffer;
     protected FileStream fs;
 
+    /**
+     * default constructor
+     * @param path the path to read
+     * @param chunk_size the chunk size
+     */
     public InputChunkStream (string path, uint8 chunk_size)
     {
         this.chunk_size  = chunk_size;
@@ -44,6 +53,10 @@ class Pluie.Io.InputChunkStream : Object
         this.fs          = FileStream.open (path, "r");
         this.chunk_index = 0;
     }
+
+    /**
+     * indicate if end of file of readed file is reached
+     */
     public bool eof ()
     {
         bool stop = this.fs.eof ();
@@ -52,6 +65,10 @@ class Pluie.Io.InputChunkStream : Object
         }
         return stop;
     }
+
+    /**
+     * read chunk_size
+     */
     public unowned uint8[] read ()
     {
         if (!this.eof ()) {
@@ -60,18 +77,34 @@ class Pluie.Io.InputChunkStream : Object
         }
         return this.buffer;
     }
+
+    /**
+     * retriew the buffer size (chunk_size)
+     */
     public unowned uint8 get_buffer_size ()
     {
         return this.buffer_size;
     }
+
+    /**
+     * retriew content of buffer
+     */
     public unowned uint8[] get_buffer ()
     {
         return this.buffer;
     }
+
+    /**
+     * retriew chunk index
+     */
     public ulong get_chunk_index ()
     {
         return this.chunk_index-1;
     }
+
+    /**
+     * retriew chunk size
+     */
     public uint8 get_chunk_size ()
     {
         return this.chunk_size;

src/vala/Pluie/Io.Reader.vala

@@ -143,7 +143,7 @@ public class Pluie.Io.Reader
     }
 
     /**
-     * 
+     * get content of loaded file
      */
     public string? get_contents ()
     {

src/vala/Pluie/Io.Writter.vala

@@ -33,7 +33,7 @@ using Gee;
 using Pluie;
 
 /**
- * basic writer
+ * basic writter class
  */
 public class Pluie.Io.Writter
 {
@@ -42,7 +42,7 @@ public class Pluie.Io.Writter
      */
     public string   path      { get; internal set; }
     /**
-     *
+     * current file
      */
     public File     file      { get; internal set; }
     /**
@@ -51,15 +51,19 @@ public class Pluie.Io.Writter
     DataOutputStream stream;
 
     /**
-     * construct a reader
+     * construct a writter
-     * by adding {@link Io.StreamLineMark}
+     * @param path the path to write
-     * @param path the path to load
+     * @param delete_if_exists flag indicating if existing file must be removed first
      */
-    public Writter (string path)
+    public Writter (string path, bool delete_if_exists = false)
     {
-        this.path   = path;
+        this.path = path;
-        this.file   = File.new_for_path (path);
+        this.file = File.new_for_path (path);
         try {
+            if (delete_if_exists) {
+                this.delete_file(this.file);
+            }
+            this.file   = File.new_for_path (path);
             this.stream = new DataOutputStream(file.create (FileCreateFlags.NONE));
             if (!file.query_exists ()) {
                 of.error ("cannot create file '%s'".printf (path));
@@ -71,25 +75,42 @@ public class Pluie.Io.Writter
     }
 
     /**
-     * read current stream by line
+     * write specified data to current file
-     * @param mark a mark used to operate possible future rewind
+     * @param data the data to write
-     * @return current readed line
+     * @param written the written data size
      */
-    public bool write (uint8[] data)
+    public bool write (uint8[] data, out long? written = null)
+    {
+        bool done = false;
+        long w = 0;
+        try {
+            while (w < data.length) { 
+                // sum of the bytes that already have been written to the stream
+                w += stream.write (data[w:data.length]);
+            }
+            done = w == data.length;
+        }
+        catch (GLib.Error e) {
+            of.error (e.message);
+        }
+        written = w;
+        return done;
+    }
+
+    /**
+     * delete current or specified file
+     * @param file the file to delete (current file if null)
+     */
+    public bool delete_file(File? file = null)
     {
         bool done = false;
         try {
-            long written = 0;
+            ((file == null) ? this.file : file).delete ();
-            while (written < data.length) { 
+            done = true;
-                // sum of the bytes that already have been written to the stream
-                written += stream.write (data[written:data.length]);
-            }
-            done = written == data.length;
         }
         catch (GLib.Error e) {
             of.error (e.message);
         }
         return done;
     }
-
 }

src/vala/Pluie/Yaml.AbstractChild.vala

@@ -88,7 +88,7 @@ public abstract class Pluie.Yaml.AbstractChild : Yaml.AbstractNode
     }
 
     /**
-     * check if first chikd
+     * check if last chikd
      */
     public bool is_last ()
     {
@@ -96,7 +96,7 @@ public abstract class Pluie.Yaml.AbstractChild : Yaml.AbstractNode
     }
 
     /**
-     * check if first chikd
+     * get nextt sibling node
      */
     public Yaml.Node? next_sibling ()
     {
@@ -104,7 +104,7 @@ public abstract class Pluie.Yaml.AbstractChild : Yaml.AbstractNode
     }
 
     /**
-     * check if first chikd
+     * get previous sibling node
      */
     public Yaml.Node? previous_sibling ()
     {
@@ -124,6 +124,9 @@ public abstract class Pluie.Yaml.AbstractChild : Yaml.AbstractNode
         return done;
     }
 
+    /**
+     * coutn childs. return 0
+     */
     public virtual int count ()
     {
         return 0;

src/vala/Pluie/Yaml.AbstractNode.vala

@@ -89,6 +89,16 @@ public abstract class Pluie.Yaml.AbstractNode : GLib.Object
         return node != null && node.uuid == this.uuid;
     }
 
+    /**
+     * get a presentation string of current Yaml.Node
+     * @param withIndent display indentation formating
+     * @param withParent display parent node name
+     * @param withUuid display node uuid
+     * @param withCount display number of childs
+     * @param withRefCount display number of reference
+     * @param withTag display tag information
+     * @param withType display node type
+     */
     public virtual string to_string (
         bool withIndent   = Yaml.DBG_SHOW_INDENT, 
         bool withParent   = Yaml.DBG_SHOW_PARENT, 
@@ -104,7 +114,12 @@ public abstract class Pluie.Yaml.AbstractNode : GLib.Object
     }
  
     /**
-     * get a yaml presentation of current Yaml.Node
+     * get a gracefull yaml presentation of current Yaml.Node
+     * @param indent number of space for indentation
+     * @param show_doc flag indicating if the document start must be print
+     * @param show_tags flag indicating if tags must be print
+     * @param show_fullkeys flag indicating if full key definition must be print
+     *
      */
     public string to_yaml_string (
         int indent         = Yaml.Dumper.DEFAULT_INDENT, 

src/vala/Pluie/Yaml.Builder.vala

@@ -54,7 +54,8 @@ public class Pluie.Yaml.Builder
     }
 
     /**
-     *
+     * retriew GLib.Type related to specified vala name
+     * type must be registered
      */
     public static GLib.Type? type_from_string (string name)
     {
@@ -64,6 +65,7 @@ public class Pluie.Yaml.Builder
 
     /**
      * retriew GLib.Type related to specified vala name
+     * type may be not registered
      * @param name a valid vala identifier name
      */
     public static Type type_from_vala (string name)
@@ -120,7 +122,9 @@ public class Pluie.Yaml.Builder
     private delegate Type dlgType();
 
     /**
-     *
+     * Build an Object from a YYaml.Node
+     * @param node the source Yaml.Node
+     * @param otype used for recursion only
      */
     public static GLib.Object? from_node (Yaml.Node node, Type otype = GLib.Type.INVALID)
     {
@@ -173,7 +177,7 @@ public class Pluie.Yaml.Builder
     /**
      *
      */
-    public static void set_from_collection (ref GLib.Object obj, Type parentType, Yaml.Node node, Type type)
+    private static void set_from_collection (ref GLib.Object obj, Type parentType, Yaml.Node node, Type type)
     {
         Yaml.dbg (" > set_from_collection %s (%s)".printf (node.name, type.name ()));
         if (type.is_a (typeof (Yaml.Object)) || Yaml.Register.is_registered_type (parentType, type)) {
@@ -187,7 +191,7 @@ public class Pluie.Yaml.Builder
     /**
      *
      */
-    public static void set_from_scalar (ref GLib.Object obj, string name, GLib.Type type, string data)
+    private static void set_from_scalar (ref GLib.Object obj, string name, GLib.Type type, string data)
     {
         GLib.Value v = GLib.Value(type);
         Yaml.dbg_action ("Auto setting property value %s".printf (of.c (ECHO.MICROTIME).s (type.name ())), name);
@@ -296,7 +300,7 @@ public class Pluie.Yaml.Builder
     /**
      *
      */
-    public static void set_enum_value (ref Value v, GLib.Type type, string data)
+    private static void set_enum_value (ref Value v, GLib.Type type, string data)
     {
         EnumClass kenum = (EnumClass) type.class_ref();
         unowned EnumValue? enumval = kenum.get_value_by_name(data);
@@ -314,7 +318,7 @@ public class Pluie.Yaml.Builder
 //~         of.echo ("enumValue : %d".printf (enumval.value));
     }
 
-    public static string transform_param_name (string name)
+    private static string transform_param_name (string name)
     {
         return name.replace("-", "_");
     }
@@ -322,6 +326,19 @@ public class Pluie.Yaml.Builder
     /**
      *
      */
+    private static Yaml.Tag add_tag (GLib.Type type)
+    {
+        return new Yaml.Tag (Yaml.Register.resolve_namespace_type(type), Yaml.YAML_VALA_PREFIX);
+    }
+
+    /**
+     * transform an Yaml.Object to  his corresponding Yaml.Node
+     * @param obj the obj to transform
+     * @param parent the parent node
+     * @param root indicates if node must be add to a root node, if true a Yaml.Root node is return
+     * @param index for sequence entry anonymous mapping block
+     * @param property_name name of property name related to obj
+     */
     public static Yaml.Node to_node (GLib.Object obj, Yaml.Node? parent = null, bool root = true, int? index = null, string? property_name = null)
     { 
         string node_name = "";
@@ -339,7 +356,7 @@ public class Pluie.Yaml.Builder
                 if (def.value_type.is_a (typeof (Yaml.Object)) || Yaml.Register.is_registered_type(obj.get_type (), def.value_type)) {
                     var child = (obj as Yaml.Object).populate_to_node(name, def.value_type, node);
                     if (child != null) {
-                        child.tag = new Yaml.Tag (Yaml.Register.resolve_namespace_type(def.value_type), "v");
+                        child.tag = Yaml.Builder.add_tag (def.value_type);
                         node.add (child);
                     }
                 }
@@ -348,7 +365,7 @@ public class Pluie.Yaml.Builder
                     obj.get (name, out enumval);
                     string data = enumval.value.to_string ();
                     var n = new Yaml.Mapping.with_scalar (node, name, (string) data);
-                    n.tag = new Yaml.Tag (Yaml.Register.resolve_namespace_type(def.value_type), "v");
+                    n.tag = Yaml.Builder.add_tag (def.value_type);
                 }
                 else if (def.value_type.is_fundamental ()) {
                     string data = Yaml.Builder.get_basic_type_value(obj, def.value_type, name);
@@ -361,13 +378,7 @@ public class Pluie.Yaml.Builder
                 }
             }
         }
-        node.tag = new Yaml.Tag (Yaml.Register.resolve_namespace_type(obj.get_type ()), "v");
+        node.tag = Yaml.Builder.add_tag (obj.get_type ());
-        if (root) {
+        return root ? new Yaml.Root(null, true, node) : node;
-            var rootNode = new Yaml.Root();
-            rootNode.add (node);
-            rootNode.tag_directives["!v!"] = "tag:pluie.org,2018:vala/";
-            return rootNode;
-        }
-        else return node;
     }
 }

src/vala/Pluie/Yaml.Collection.vala

@@ -38,14 +38,15 @@ using Pluie;
 public interface Pluie.Yaml.Collection
 {
     /**
-     * retriew the child at index
+     * retriew a child node throught specifiyed index
-     * @param   index index of seached child
+     * @param index index of searched child
+     * @return the matching child node
      */
     public abstract Yaml.Node? item (int index);
 
     /**
-     * check if contains specifyed child node
+     * check if current node contains the specifiyed child node
-     * @param   child the child to check 
+     * @param child the child to check 
      */
     public abstract bool contains (Yaml.Node child);
 
@@ -67,23 +68,25 @@ public interface Pluie.Yaml.Collection
 
     /**
      * retriew the first child
+     * @return the first child node
      */
     public abstract Yaml.Node? first ();
 
     /**
      * retriew the last child
+     * @return the last child node
      */
     public abstract Yaml.Node? last ();
 
     /**
      * retriew the next sibling of specifiyed child node
-     * @param   child the the reference child node
+     * @param child the the reference child node
      */
     public abstract Yaml.Node? child_next_sibling (Yaml.Node child);
 
     /**
      * retriew the previous sibling of specifiyed child node
-     * @param   child the the reference child node
+     * @param child the the reference child node
      */
     public abstract Yaml.Node? child_previous_sibling (Yaml.Node child);
 

src/vala/Pluie/Yaml.Config.vala

@@ -29,12 +29,12 @@
  */
 
 /**
- * a class to manage Yaml configuration files
+ * Yaml.Config class to manage Yaml configuration files
  */
 public class Pluie.Yaml.Config
 {
     /**
-     *
+     * special char use in imports clause & imports var
      */
     const char                  IMPORTS_SPE = '^';
 
@@ -46,7 +46,7 @@ public class Pluie.Yaml.Config
     /**
      *
      */
-    public bool                 displayFile     { get; internal set; }
+    public bool                 display_file    { get; internal set; }
 
     /**
      * Yaml Loader
@@ -70,14 +70,17 @@ public class Pluie.Yaml.Config
 
     /**
      * construct a Yaml Config for specifiyed path
+     * @param path the yaml path file to load
+     * @param display_file flag to display file
+     * @param mode Yaml.FIND_MODE to apply to finder
      */
-    public Config (string? path = null, bool displayFile = false, Yaml.FIND_MODE mode = Yaml.FIND_MODE.DOT)
+    public Config (string? path = null, bool display_file = false, Yaml.FIND_MODE mode = Yaml.FIND_MODE.DOT)
     {
         Yaml.MODE          = mode;
         this.path          = path;
-        this.displayFile   = displayFile;
+        this.display_file  = display_file;
         if (this.path != null) {
-            this.loader = new Yaml.Loader (this.path, displayFile, false);
+            this.loader = new Yaml.Loader (this.path, display_file, false);
             Yaml.Node? root = this.loader.get_nodes ();
             if (root != null) {
                 this.finder = new Yaml.Finder(root);
@@ -88,6 +91,7 @@ public class Pluie.Yaml.Config
 
     /**
      * find node matching specifiyed keyPath
+     * see {@link Yaml.Finder} for precisions
      */
     public new Yaml.Node? get (string keyPath)
     {
@@ -99,7 +103,7 @@ public class Pluie.Yaml.Config
     }
 
     /**
-     *
+     * retriew the corresponding Yaml.Root node for loaded yaml file
      */
     public Yaml.Root root_node ()
     {
@@ -107,7 +111,7 @@ public class Pluie.Yaml.Config
     }
 
     /**
-     * find node matching specifiyed keyPath
+     *
      */
     protected void get_imports ()
     {
@@ -138,7 +142,7 @@ public class Pluie.Yaml.Config
         Yaml.Node? n    = null;
         Yaml.Config?  conf = null;
         foreach(var entry in this.paths.entries) {
-            conf = new Yaml.Config(entry.value, this.displayFile);
+            conf = new Yaml.Config(entry.value, this.display_file);
             sub  = conf.loader.get_nodes ();
             n    = new Yaml.Mapping (root, entry.key);
             foreach(var subnode in sub.list) {

src/vala/Pluie/Yaml.Dumper.vala

@@ -33,36 +33,36 @@ using Gee;
 using Pluie;
 
 /**
- * interface representing a collection node
+ * a Yaml.Dumper to dump a Yaml.Node to his file representation
  */
 public class Pluie.Yaml.Dumper
 {
     /**
-     *
+     * default number space indentation to apply for all nodes. default : 4
      */
     public static int  DEFAULT_INDENT { get; internal set; default = 4; }
     /**
-     *
+     * flag indicating if the document start must be print
      */
     public static bool SHOW_DOC       { get; internal set; default = true; }
     /**
-     *
+     * flag indicating if tags must be print
      */
     public static bool SHOW_TAGS      { get; internal set; default = true; }
     /**
-     *
+     * flag indicating if full key definition must be print
      */
     public static bool SHOW_FULL_KEYS { get; internal set; default = false; }
     /**
-     *
+     * flag indicating if enable printing colors
      */
     static bool        SHOW_COLOR     { get; internal set; default = false; }
     /**
-     *
+     * flag indicating if line number must be print
      */
     static bool        SHOW_LINE      { get; internal set; default = false; }
     /**
-     *
+     * a line counter
      */
     static int         line           { get; internal set; default = 0; }
 
@@ -75,6 +75,13 @@ public class Pluie.Yaml.Dumper
 
     /**
      * get a gracefull yaml presentation of current Yaml.Node
+     * @param node the node to dump
+     * @param flag indicating if enable printing colors
+     * @param show_line flag indicating if line number must be print
+     * @param show_tags flag indicating if tags must be print
+     * @param show_doc flag indicating if the document start must be print
+     * @param indent number of space for indentation
+     * @param show_fullkeys flag indicating if full key definition must be print
      */
     public static void show_yaml_string (
         Yaml.Node? node, 
@@ -96,7 +103,12 @@ public class Pluie.Yaml.Dumper
     }
 
     /**
-     * get a yaml presentation of current Yaml.Node
+     * get a yaml presentation of specified Yaml.Node
+     * @param node the node to dump
+     * @param indent number of space for indentation
+     * @param show_doc flag indicating if the document start must be print
+     * @param show_tags flag indicating if tags must be print
+     * @param show_fullkeys flag indicating if full key definition must be print
      */
     public static string dump (
         Yaml.Node? node, 

src/vala/Pluie/Yaml.Event.vala

@@ -33,7 +33,8 @@ using Gee;
 using Pluie;
 
 /**
- * Yaml Event class
+ * Yaml Event class populated by {@link Yaml.Scanner} and treat by the {@link Yaml.Processor} to
+ * build a {@link Yaml.Node} from a yaml.file
  */
 public class Pluie.Yaml.Event
 {

src/vala/Pluie/Yaml.GeeBuilder.vala

@@ -33,12 +33,16 @@ using Gee;
 using Pluie;
 
 /**
- * a Yaml.Builder class helping to build vala Yaml.Object from Yaml.Node
+ * a Yaml.GeeBuilder class helping to build vala Gee.Collection with fundamental type to Yaml.Node
  */
 public class Pluie.Yaml.GeeBuilder
 {
     /**
-     *
+     * transform a Gee.Collection with fundamental type to a Yaml.Node
+     * @param Gee.ArrayList* a pointer to the list
+     * @param property_name name of related property
+     * @param parent parent Yaml.Node of the list
+     * @param is_char flag indicating data with char representation
      */
     public static Yaml.Node? fundamental_arraylist_to_node (Gee.ArrayList* o, string property_name, Yaml.Node parent, bool is_char = false)
     {

src/vala/Pluie/Yaml.Loader.vala

@@ -38,7 +38,7 @@ using Pluie;
 public class Pluie.Yaml.Loader
 {
     /**
-     * Scanner 
+     * Yaml.Scanner used to retriew yaml events
      */
     Yaml.Scanner    scanner     { public get; internal set; }
 
@@ -53,15 +53,16 @@ public class Pluie.Yaml.Loader
     Io.Reader       reader;
 
     /**
+     * default constructor of Yaml.Loader
      * @param path the path of file to parse
-     * @param displayFile display original file
+     * @param display_file display original file
      * @param displayNode display corresponding Yaml Node Graph
      */
-    public Loader (string path, bool displayFile = false, bool displayNode = false )
+    public Loader (string path, bool display_file = false, bool displayNode = false )
     {
         this.reader  = new Io.Reader (path);
         this.scanner = new Yaml.Scanner (path);
-        if (displayFile) this.displayFile ();
+        if (display_file) this.display_file ();
 
         if ((this.done = this.scanner.run())) {
             if (displayNode) {
@@ -73,7 +74,7 @@ public class Pluie.Yaml.Loader
         else {
             var evt = this.scanner.get_error_event ();
             of.error ("line %d (%s)".printf (evt.line, evt.data["error"]));
-            this.displayFile (evt.line);
+            this.display_file (evt.line);
         }
     }
 
@@ -87,8 +88,9 @@ public class Pluie.Yaml.Loader
 
     /**
      * display original file
+     * @param errorLine  highlight error line
      */
-    public void displayFile (int errorLine = 0)
+    public void display_file (int errorLine = 0)
     {
         of.action (errorLine == 0 ? "Reading file" : "Invalid Yaml File", this.reader.path);
         of.echo ();

src/vala/Pluie/Yaml.Mapping.vala

@@ -43,7 +43,9 @@ public class Pluie.Yaml.Mapping : Yaml.Node
     Gee.ArrayList<string>?              keys       { internal get; internal set; default = null; }
 
     /**
-     *
+     * default Yaml.Mapping constructor
+     * @param parent the parent node
+     * @param name the node name
      */
     public Mapping (Yaml.Node? parent = null, string? name = null)
     {
@@ -52,7 +54,10 @@ public class Pluie.Yaml.Mapping : Yaml.Node
     }
 
     /**
-     *
+     * Yaml.Mapping constructor as single pair node with scalar data
+     * @param parent the parent node
+     * @param name the node name
+     * @param data scalar data
      */
     public Mapping.with_scalar (Yaml.Node? parent = null, string? name = null, string? data = null)
     {
@@ -62,8 +67,7 @@ public class Pluie.Yaml.Mapping : Yaml.Node
     }
 
     /**
-     * add a child node to current collection (mapping or sequence) node
+     * {@inheritDoc}
-     * @param child the Yaml.Node child to add
      */
     protected override void before_add (Yaml.Node child) throws Yaml.AddNodeError
     {
@@ -84,8 +88,7 @@ public class Pluie.Yaml.Mapping : Yaml.Node
     }
 
     /**
-     * add a child node to current collection (mapping or sequence) node
+     * {@inheritDoc}
-     * @param child the Yaml.Node child to add
      */
     protected override void on_added (Yaml.Node child)
     {
@@ -99,9 +102,7 @@ public class Pluie.Yaml.Mapping : Yaml.Node
     }
 
     /**
-     * add a child node to current collection (mapping or sequence) node
+     * {@inheritDoc}
-     * @param child the Yaml.Node child to add
-     * @param levelUpdate flag indicating if update level is needed
      */
     protected override void on_removed (Yaml.Node child, bool levelUpdate = true)
     {
@@ -112,9 +113,9 @@ public class Pluie.Yaml.Mapping : Yaml.Node
     }
 
     /**
-     * retriew a child node throught specifiyed index
+     * retriew a child node throught specifiyed name
      * @param name name of searched child
-     * @return the child node
+     * @return the matching child node
      */
     public new Yaml.Node? item (string name)
     {
@@ -129,8 +130,7 @@ public class Pluie.Yaml.Mapping : Yaml.Node
     }
 
     /**
-     * clone current node
+     * {@inheritDoc}
-     * @param name the overrinding name
      */
     public override Yaml.Node clone_node (string? name = null)
     {
@@ -145,7 +145,7 @@ public class Pluie.Yaml.Mapping : Yaml.Node
     }
 
     /**
-     *
+     * get a collection of chils name
      */
     public Gee.ArrayList<string>? child_names ()
     {

src/vala/Pluie/Yaml.Node.vala

@@ -31,7 +31,7 @@ using GLib;
 using Gee;
 
 /**
- * a class representing a node
+ * a class representing a yaml node no matter was his type
  */
 public class Pluie.Yaml.Node : Yaml.AbstractChild, Pluie.Yaml.Collection
 {
@@ -81,8 +81,9 @@ public class Pluie.Yaml.Node : Yaml.AbstractChild, Pluie.Yaml.Collection
     }
 
     /**
-     * add a child node to current collection (mapping or sequence) node
+     * actions to execute before adding the specified child bode
      * @param child the Yaml.Node child to add
+     * @throws Yaml.AddNodeError
      */
     protected virtual void before_add (Yaml.Node child) throws Yaml.AddNodeError
     {
@@ -90,7 +91,7 @@ public class Pluie.Yaml.Node : Yaml.AbstractChild, Pluie.Yaml.Collection
     }
 
     /**
-     * add a child node to current collection (mapping or sequence) node
+     * actions to execute after adding the specified child bode
      * @param child the Yaml.Node child to add
      */
     protected virtual void on_added (Yaml.Node child)
@@ -100,7 +101,8 @@ public class Pluie.Yaml.Node : Yaml.AbstractChild, Pluie.Yaml.Collection
 
     /**
      * remove a child
-     * @param child  the child to remove
+     * @param child the child to remove
+     * @param levelUpdate flag indacting if level must be updated
      */
     public bool remove_child (Yaml.Node child, bool levelUpdate = true)
     {
@@ -114,8 +116,9 @@ public class Pluie.Yaml.Node : Yaml.AbstractChild, Pluie.Yaml.Collection
     }
 
     /**
-     * add a child node to current collection (mapping or sequence) node
+     * action to exectuing after removing the specified child node
-     * @param child the Yaml.Node child to add
+     * @param child the Yaml.Node child to remove
+     * @param levelUpdate flag indacting if level must be updated for removed child
      */
     protected virtual void on_removed (Yaml.Node child, bool levelUpdate = true)
     {
@@ -126,9 +129,7 @@ public class Pluie.Yaml.Node : Yaml.AbstractChild, Pluie.Yaml.Collection
     }
 
     /**
-     * retriew a child node throught specifiyed index
+     * {@inheritDoc}
-     * @param index index of searched child
-     * @return the child node
      */
     public virtual Yaml.Node? item (int index)
     {
@@ -136,37 +137,35 @@ public class Pluie.Yaml.Node : Yaml.AbstractChild, Pluie.Yaml.Collection
     }
 
     /**
-     * check if current node contains the specifiyed child node
+     * {@inheritDoc}
-     * @param   child the child to check 
      */
     public bool contains (Yaml.Node child) {
         return !this.empty () && this.list.contains (child);
     }
 
     /**
-     * count childnodes
+     * {@inheritDoc}
      */
     public override int count () {
         return !this.empty () ? this.list.size : 0;
     }
 
     /**
-     * check if empty
+     * {@inheritDoc}
      */
     public bool empty () {
         return this.list == null || this.list.size == 0;
     }
 
     /**
-     * get an iterator
+     * {@inheritDoc}
      */
     public Gee.Iterator<Yaml.Node> iterator () {
         return this.list.iterator ();
     }
 
     /**
-     * retriew the first child node
+     * {@inheritDoc}
-     * @return the first child node
      */
     public virtual Yaml.Node? first ()
     {
@@ -174,8 +173,7 @@ public class Pluie.Yaml.Node : Yaml.AbstractChild, Pluie.Yaml.Collection
     }
 
     /**
-     * retriew the last child node
+     * {@inheritDoc}
-     * @return the last child node
      */
     public Yaml.Node? last ()
     {
@@ -198,7 +196,7 @@ public class Pluie.Yaml.Node : Yaml.AbstractChild, Pluie.Yaml.Collection
     }
 
     /**
-     *
+     * {@inheritDoc}
      */
     public Yaml.Node? child_next_sibling (Yaml.Node child)
     {
@@ -206,15 +204,15 @@ public class Pluie.Yaml.Node : Yaml.AbstractChild, Pluie.Yaml.Collection
     }
 
     /**
-     *
+     * {@inheritDoc}
      */
     public Yaml.Node? child_previous_sibling (Yaml.Node child)
     {
         return this.child_sibling (child, false);
     }
 
-    /*
+    /**
-     *
+     * update nested indention node level and propagate approprietly level to all childs
      */
     public virtual void update_level()
     {
@@ -227,8 +225,9 @@ public class Pluie.Yaml.Node : Yaml.AbstractChild, Pluie.Yaml.Collection
     }
 
     /**
-     * clone current node
+     * clone current node (with all his children)
-     * @param name the name of clone
+     * @param name the name of the clone
+     * @return the cloned node with cloned childs
      */
     public virtual Yaml.Node clone_node (string? name = null)
     {
@@ -243,16 +242,16 @@ public class Pluie.Yaml.Node : Yaml.AbstractChild, Pluie.Yaml.Collection
     }
 
     /**
-     * clone current node
+     *
-     * @param name the name of clone
      */
-    public virtual Yaml.Node get_cloned_instance (string? name = null)
+    internal virtual Yaml.Node get_cloned_instance (string? name = null)
     {
         return new Yaml.Node (null, this.ntype, name);
     }
 
     /**
-     *
+     * retriew the GLib.Value initialized with specified type (only) for single pair node
+     * return the pair value
      */
     public GLib.Value val (GLib.Type type)
     {
@@ -265,6 +264,7 @@ public class Pluie.Yaml.Node : Yaml.AbstractChild, Pluie.Yaml.Collection
 
     /**
      * display childs
+     * @param withTitle display a title before the childs node presentation
      */
     public void display_childs (bool withTitle = true)
     {
@@ -282,6 +282,13 @@ public class Pluie.Yaml.Node : Yaml.AbstractChild, Pluie.Yaml.Collection
 
     /**
      * get a presentation string of current Yaml.Node
+     * @param withIndent display indentation formating
+     * @param withParent display parent node name
+     * @param withUuid display node uuid
+     * @param withCount display number of childs
+     * @param withRefCount display number of reference
+     * @param withTag display tag information
+     * @param withType display node type
      */
     public override string to_string (
         bool withIndent   = Yaml.DBG_SHOW_INDENT, 

src/vala/Pluie/Yaml.Object.vala

@@ -31,22 +31,22 @@ using GLib;
 using Gee;
 
 /**
- * Yaml.Object bqse class which can be transform to a Yaml.Node structure
+ * Yaml.Object base class which can be transform to a Yaml.Node structure
  */
 public abstract class Pluie.Yaml.Object : GLib.Object
 {
     /**
-     *
+     * Yaml node name
      */
     public string               yaml_name { get; internal set; }
 
     /**
-     *
+     * associated Yaml.Register for tag resolution (full namespace names)
      */
     public static Yaml.Register register  { get; private set; }
 
     /**
-     *
+     * Yaml.Tag definition
      */
     public static Yaml.Tag      yaml_tag  { get; internal set; }
 
@@ -69,7 +69,7 @@ public abstract class Pluie.Yaml.Object : GLib.Object
     }
 
     /**
-     *
+     * default constructor
      */
     public virtual void yaml_construct ()
     {
@@ -77,7 +77,8 @@ public abstract class Pluie.Yaml.Object : GLib.Object
     }
 
     /**
-     *
+     * initialization method called by Yaml.Builder after instantiation
+     * and after properties has been populated
      */
     public virtual void yaml_init ()
     {
@@ -85,7 +86,10 @@ public abstract class Pluie.Yaml.Object : GLib.Object
     }
 
     /**
-     *
+     * build property name from a Yaml.Node
+     * @param name name the property to build
+     * @param type type the property type
+     * @param node the Yaml.Node source
      */
     public virtual signal void populate_from_node (string name, GLib.Type type, Yaml.Node node) {
         if (type.is_a(typeof (Yaml.Object))) {
@@ -98,7 +102,11 @@ public abstract class Pluie.Yaml.Object : GLib.Object
     }
 
     /**
-     *
+     * convert property name to a Yaml.node
+     * @param name name of the property to build
+     * @param type type of the property to build
+     * @param parent parent node of the property
+     * @return the resulting Yaml.Node
      */
     public virtual signal Yaml.Node? populate_to_node (string name, GLib.Type type, Yaml.Node parent) {
         Yaml.Node? node = null;
@@ -111,7 +119,11 @@ public abstract class Pluie.Yaml.Object : GLib.Object
     }
 
     /**
-     *
+     * build an object collection (Gee.Collection) to a Yaml.Node
+     * @param list the gee collection to transform
+     * @param name name of collection sequence node
+     * @param parent parent node of the collection
+     * @return the resulting Yaml.Node
      */
     public static Yaml.Node? objects_collection_to_node (Gee.Collection list, string name, Yaml.Node? parent = null)
     {
@@ -121,7 +133,7 @@ public abstract class Pluie.Yaml.Object : GLib.Object
         var it = list.iterator ();
         var i  = 0;
         while (it.next ()) {
-            var s = Yaml.Builder.to_node (
+            Yaml.Builder.to_node (
                 (GLib.Object) it.get (),
                 node, 
                 false,

src/vala/Pluie/Yaml.Processor.vala

@@ -277,7 +277,7 @@ public class Pluie.Yaml.Processor
     }
 
     /**
-     * retriew the next Yaml Value Event
+     * retriew the next Yaml Value Event without use of iterator
      */
     private Yaml.Event? get_next_value_event ()
     {
@@ -315,6 +315,14 @@ public class Pluie.Yaml.Processor
         this.error_event = this.event;
     }
 
+    /**
+     *
+     */
+    private bool is_entry_nested_block (Yaml.Node node)
+    {
+        return node.ntype.is_sequence () && !node.empty() && node.first ().ntype.is_collection ();
+    }
+
     /**
      *
      */
@@ -323,14 +331,14 @@ public class Pluie.Yaml.Processor
         if (!this.prev_node.ntype.is_collection ()) {
             this.prev_node = this.prev_node.parent;
         }
-        bool isSequenceWithBlock = this.prev_node.ntype.is_sequence () && !this.prev_node.empty() && this.prev_node.first ().ntype.is_collection ();
+        bool is_nested = this.is_entry_nested_block (this.prev_node);
-        if (!isSequenceWithBlock || (isSequenceWithBlock && (this.prev_node as Yaml.Sequence).close_block)) {
+        if (!is_nested || (is_nested && (this.prev_node as Yaml.Sequence).close_block)) {
             this.parent_node = this.prev_node.parent != null && this.prev_node.parent != this.root 
             ? this.prev_node.parent
             : this.root;
             this.prev_node   = this.parent_node;
         }
-        if (isSequenceWithBlock) {
+        if (is_nested) {
             var seq = this.prev_node as Yaml.Sequence;
             if (seq != null) {
                 seq.close_block = true;
@@ -345,6 +353,7 @@ public class Pluie.Yaml.Processor
     {
         this.event = this.next_event();
         Yaml.Event? e = null;
+        // look up for sequence enrty nested block
         e = get_next_value_event ();
         if (this.event.evtype.is_mapping_start () && (e!= null && !e.evtype.is_mapping_start ())) {
             this.on_mapping_start (true);

src/vala/Pluie/Yaml.Root.vala

@@ -33,27 +33,33 @@ using Pluie;
 using Gee;
 
 /**
- * a class representing a mapping node
+ * a class representing a Yaml Root Node
  */
 public class Pluie.Yaml.Root : Yaml.Mapping
 {
     /**
-     * Tags map definition
+     * Tags directives
      */
     public Gee.HashMap<string, string>    tag_directives { get; internal set; }
 
     /**
-     *
+     * @param name the name of the root node
      */
-    public Root (string? name = "PluieYamlRoot")
+    public Root (string? name = "PluieYamlRoot", bool add_directive = false, Yaml.Node? child = null)
     {
         base (null, name);
         this.ntype = Yaml.NODE_TYPE.ROOT;
         this.tag_directives = new Gee.HashMap<string, string> ();
+        if (add_directive) {
+            this.tag_directives["!%s!".printf (Yaml.YAML_VALA_PREFIX)] = Yaml.YAML_VALA_DIRECTIVE;
+        }
+        if (child != null) {
+            this.add (child);
+        }
     }
 
     /**
-     *
+     * get tag directives formatted for colorized output
      */
     public string get_display_tag_directives ()
     {

src/vala/Pluie/Yaml.Scalar.vala

@@ -48,7 +48,8 @@ public class Pluie.Yaml.Scalar : Yaml.Node
     public Scalar (Yaml.Node ? parent = null, string? data = null)
     {
         base (parent, NODE_TYPE.SCALAR);
-        this.data = data;
+        this.container = false;
+        this.data      = data;
     }
 
     /**

src/vala/Pluie/Yaml.Scanner.vala

@@ -126,7 +126,7 @@ public class Pluie.Yaml.Scanner
     {
         var f = GLib.File.new_for_path (this.path);
         try {
-//~             f.delete ();
+            f.delete ();
         }
         catch (GLib.Error e) {
             of.error (e.message);

src/vala/Pluie/Yaml.Sequence.vala

@@ -37,7 +37,7 @@ using Gee;
  */
 public class Pluie.Yaml.Sequence : Yaml.Node
 {
-    public bool close_block { get; internal set; default = false; }
+    internal bool close_block { internal get; internal set; default = false; }
 
     /**
      * default Yaml.Node constructor

src/vala/Pluie/Yaml.global.vala

@@ -33,6 +33,8 @@ namespace Pluie
     namespace Yaml
     {
         const string YAML_VERSION          = "1.2";
+        const string YAML_VALA_PREFIX      = "v";
+        const string YAML_VALA_DIRECTIVE   = "tag:pluie.org,2018:vala/";
 
         public static bool DEBUG           = false;
 
@@ -103,7 +105,7 @@ namespace Pluie
         /**
          *
          */
-        public static uint8[] serialize (GLib.Object? obj)
+        public static uint8[] serialize (GLib.Object? obj, string? dest = null)
         {
             Array<uint8> a = new Array<uint8> ();
             if (obj != null) {
@@ -112,16 +114,21 @@ namespace Pluie
                     var content = node.to_yaml_string ();
                     var date    = new GLib.DateTime.now_local ().format ("%s");
                     var path    = Path.build_filename (Environment.get_tmp_dir (), "pluie-yaml-%s-%s.source".printf (date, node.uuid));
+                    var dpath   = dest == null ? path + ".gz" : dest;
                     var writter = new Io.Writter (path);
                     if (writter.write (content.data)) {
                         try {
-                            var gzfile = File.new_for_path (path + ".gz");
+                            var gzfile = File.new_for_path (dpath);
                             convert (writter.file, gzfile, new ZlibCompressor (ZFORMAT));
-                            var reader = new Io.InputChunkStream(path + ".gz", 80);
+                            var reader = new Io.InputChunkStream(dpath, 80);
                             while (!reader.eof ()) {
                                 var b = reader.read ();
                                 a.append_vals (b, reader.get_buffer_size ());
                             }
+                            writter.delete_file ();
+                            if (dest == null) {
+                                writter.delete_file (gzfile);
+                            }
                         }
                         catch (GLib.Error e) {
                             of.error (e.message);
@@ -148,6 +155,7 @@ namespace Pluie
                     convert (writter.file, file, new ZlibDecompressor (ZFORMAT));
                     var config = new Yaml.Config (dpath);
                     obj = config.root_node ();
+                    writter.delete_file ();
                 }
             }
             return obj;