improve doc

src/install.vala

@@ -27,8 +27,38 @@
  *
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *^*/
 
+/**
+ * root namespace of various Pluie lib
+ */
 namespace Pluie
 {
+    /**
+     * Pluie.Io is dedicated to various input/ouput operations
+     */
+    namespace Io
+    {
+        
+    }
+
+    /**
+     * Samples namespace  to illustrate or test functionnalities
+     */
+    namespace Samples
+    {
+        
+    }
+
+    /**
+     * Pluie.Yaml provides various tools to deal with yaml files and yaml nodes :
+     *
+     * Use {@link Yaml.Config} to load a .yml file and build a {@link Yaml.Root} node<<BR>>
+     * Use {@link Yaml.Config.get} to retriew a particular {@link Yaml.Node}<<BR>>
+     * Use {@link Yaml.Builder} to convert a {@link Yaml.Node} into a {@link Yaml.Object}<<BR>>
+     * Use {@link Yaml.Dumper} to dump a {@link Yaml.Object} or {@link Yaml.Node} into a yaml string<<BR>>
+     * Use {@link Yaml.serialize} to serialize a {@link Yaml.Object} or {@link Yaml.Node} into a string<<BR>>
+     * Use {@link Yaml.deserialize} to deserialize a serialized string into a {@link Yaml.Node}<<BR>>
+     * Use {@link Yaml.Collection} and {@link Yaml.AbstractChild} methods for Node traversing
+     */
     namespace Yaml
     {
         protected const string INSTALL_PATH = "@INSTALL_PATH@";

src/vala/Pluie/Io.InputChunkStream.vala

@@ -34,10 +34,25 @@ using GLib;
  */
 class Pluie.Io.InputChunkStream : Object
 {
+    /**
+     *
+     */
     protected ulong      chunk_index;
+    /**
+     *
+     */
     protected uint8      chunk_size;
+    /**
+     *
+     */
     protected uint8      buffer_size;
+    /**
+     *
+     */
     protected uint8[]    buffer;
+    /**
+     *
+     */
     protected FileStream fs;
 
     /**

src/vala/Pluie/Samples.YamlChild.vala

@@ -28,7 +28,7 @@
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *^*/
 
 /**
- * a test class to implements yamlize
+ * a YamlCHild test class
  */
 public class Pluie.Samples.YamlChild : Yaml.Object
 {

src/vala/Pluie/Samples.YamlObject.vala

@@ -32,7 +32,7 @@ using Gee;
 using Pluie;
 
 /**
- * a test class to implements yamlize
+ * a YamlObject test class
  */
 public class Pluie.Samples.YamlObject : Yaml.Object
 {

src/vala/Pluie/Samples.YamlStruct.vala

@@ -28,7 +28,7 @@
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *^*/
 
 /**
- *
+ * YamlStruct test structure
  */
 public struct Pluie.Samples.YamlStruct
 {
@@ -46,7 +46,8 @@ public struct Pluie.Samples.YamlStruct
     public uint blue;
 
     /**
-     *
+     * get a new YamlStruct populated by specified node
+     * @param node the source Yaml.Node
      */
     public static YamlStruct from_yaml_node (Yaml.Node node)
     {

src/vala/Pluie/Yaml.Config.vala

@@ -28,7 +28,44 @@
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *^*/
 
 /**
- * Yaml.Config class to manage Yaml configuration files
+ * Yaml.Config class to manage Yaml configuration files and provide a Yaml.Root node.
+ * 
+ * Yaml.Config use a Yaml.Finder to easily retriew a particular node. <<BR>>
+ * The Yaml.Config.get method is bind to the Yaml.Finder.find method with <<BR>>
+ * the root node as context. (more details on {@link Yaml.Finder})
+ * 
+ * {{{
+ *  var config = new Yaml.Config (path);
+ *  var node   = config.get ("ship-to.address.city{0}");
+ *  if (node != null) {
+ *      of.echo (node.data)
+ *  }
+ * }}}
+ * 
+ * You can use a special import clause to embed a set of yaml files into your current document.
+ *
+ * {{{
+ * # |  use special key word '^imports' to import other yaml config files in 
+ * # |  current yaml document
+ * # |  '^imports' must be uniq and a direct child of root node
+ * # |  imported files are injected as mapping nodes at top document level
+ * # |  so you cannot use keys that already exists in the document
+ * ^imports :
+ *    # you can redefine default import path with the special key '^path'
+ *    # if you do not use it, the default path value will be the current directory
+ *    # redefined path values are relative to the current directory (if a relative path 
+ *    # is provided)
+ *    ^path : ./config
+ *    # you can also define any other var by prefixing key with ^
+ *    ^dir  : subdir
+ *    # and use it enclosed by ^
+ *    # here final test path will be "./config/subdir/test.yml"
+ *    test  : ^dir^/test.yml 
+ *    # here final db path will be "./config/db.yml"
+ *    db    : db.yml
+ * }}}
+ * 
+ * {{doc/img/pluie-yaml-imports2.png}}
  */
 public class Pluie.Yaml.Config
 {

src/vala/Pluie/Yaml.Finder.vala

@@ -33,6 +33,19 @@ using Pluie;
 
 /**
  * Finder class used to easily retriew Yaml.Node
+ * 
+ * Path definition has two mode :
+ * default mode is ''Yaml.FIND_MODE.DOT''
+ * 
+ *  * child mapping node are separated by dot :
+ *  *  sequence entry must be enclosed in curly brace
+ *  ex : ``grandfather.father.son{2}.age``
+ * 
+ * other mode is ''Yaml.FIND_MODE.SQUARE_BRACKETS''.
+ * 
+ *  * node's key name must be enclosed in square brackets
+ *  * sequence entry must be enclosed in curly brace
+ *  ex : ``[grandfather][father][son]{2}[age]``
  */
 public class Pluie.Yaml.Finder : GLib.Object
 {
@@ -52,17 +65,7 @@ public class Pluie.Yaml.Finder : GLib.Object
     }
 
     /**
-     * find a specific child Yaml.Node corresponding to path definition
-     * path definition has two mode.
-     * default mode is Yaml.FIND_MODE.DOT
-     * - child mapping node are separated by dot :
-     * - sequence entry must be enclosed in curly brace
-     * ex : grandfather.father.son{2}.age
-     * 
-     * other mode is Yaml.FIND_MODE.DOTSQUARE_BRACKETS
-     * - node's key name must be enclosed in square brackets
-     * - sequence entry must be enclosed in curly brace
-     * ex : [grandfather][father][son]{2}[age]
+     * Find a specific child Yaml.Node corresponding to path definition.
      *
      * @param path the definition to retriew the child node
      * @param context the Yaml.Node context to operate

src/vala/Pluie/Yaml.GeeBuilder.vala

@@ -38,7 +38,6 @@ 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

src/vala/Pluie/Yaml.global.vala

@@ -27,10 +27,8 @@
  *
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *^*/
 
-namespace Pluie
+namespace Pluie.Yaml
 {
-    namespace Yaml
-    {
     const string YAML_VERSION          = "1.2";
     const string YAML_VALA_PREFIX      = "v";
     const string YAML_VALA_DIRECTIVE   = "tag:pluie.org,2018:vala/";
@@ -49,7 +47,7 @@ namespace Pluie
     /**
      *
      */
-        public static void dbg_action (string msg, string? val = null)
+    internal static void dbg_action (string msg, string? val = null)
     {
         if (Pluie.Yaml.DEBUG) of.action (msg, val);
     }
@@ -57,7 +55,7 @@ namespace Pluie
     /**
      *
      */
-        public static void dbg_keyval (string key, string val)
+    internal static void dbg_keyval (string key, string val)
     {
         if (Pluie.Yaml.DEBUG) of.keyval (key, val);
     }
@@ -65,7 +63,7 @@ namespace Pluie
     /**
      *
      */
-        public static void dbg_state (bool done)
+    internal static void dbg_state (bool done)
     {
         if (Pluie.Yaml.DEBUG) of.state (done);
     }
@@ -73,7 +71,7 @@ namespace Pluie
     /**
      *
      */
-        public static void dbg (string? msg = null)
+    internal static void dbg (string? msg = null)
     {
         if (Pluie.Yaml.DEBUG && msg != null) of.echo (msg);
     }
@@ -441,5 +439,4 @@ namespace Pluie
             h.substring (20)
         );
     }
-    }
 }

valadoc.sh

@@ -31,11 +31,11 @@
 DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 lib="pluie-yaml-0.5"
 cd $DIR
-valadoc --package-name=$lib --verbose --force --deps -o ./doc --pkg gee-0.8 --pkg gio-2.0 --pkg gobject-2.0 --pkg gmodule-2.0 --pkg glib-2.0 --pkg pluie-echo-0.2 ./src/vala/Pluie/*.vala ./build/install.vala
+valadoc --package-name=$lib --verbose --force --deps -o ./doc --pkg gee-0.8 --pkg gio-2.0 --pkg gobject-2.0 --pkg gmodule-2.0 --pkg glib-2.0 --pkg pluie-echo-0.2 ./src/vala/Pluie/*.vala ./src/install.vala
 if [ $? -eq 0 ]; then
     rm doc/*.png
     cp resources/doc-scripts.js ./doc/scripts.js
     cp resources/doc-style.css ./doc/style.css
-    rm $lib.tar.gz
-    tar -czvf $lib.tar.gz doc/
+    #~ rm $lib.tar.gz
+    #~ tar -czvf $lib.tar.gz doc/
 fi