improve doc

This commit is contained in:
a-sansara 2018-08-29 18:42:10 +02:00
parent f73d7d8545
commit 48c00f3ae5
11 changed files with 486 additions and 404 deletions

File diff suppressed because one or more lines are too long

View File

@ -27,8 +27,38 @@
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *^*/ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *^*/
/**
* root namespace of various Pluie lib
*/
namespace Pluie 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 namespace Yaml
{ {
protected const string INSTALL_PATH = "@INSTALL_PATH@"; protected const string INSTALL_PATH = "@INSTALL_PATH@";

View File

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

View File

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

View File

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

View File

@ -28,7 +28,7 @@
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *^*/ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *^*/
/** /**
* * YamlStruct test structure
*/ */
public struct Pluie.Samples.YamlStruct public struct Pluie.Samples.YamlStruct
{ {
@ -46,7 +46,8 @@ public struct Pluie.Samples.YamlStruct
public uint blue; 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) public static YamlStruct from_yaml_node (Yaml.Node node)
{ {

View File

@ -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 public class Pluie.Yaml.Config
{ {

View File

@ -33,6 +33,19 @@ using Pluie;
/** /**
* Finder class used to easily retriew Yaml.Node * 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 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 * 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]
* *
* @param path the definition to retriew the child node * @param path the definition to retriew the child node
* @param context the Yaml.Node context to operate * @param context the Yaml.Node context to operate

View File

@ -38,7 +38,6 @@ public class Pluie.Yaml.GeeBuilder
{ {
/** /**
* transform a Gee.Collection with fundamental type to a Yaml.Node * 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 property_name name of related property
* @param parent parent Yaml.Node of the list * @param parent parent Yaml.Node of the list
* @param is_char flag indicating data with char representation * @param is_char flag indicating data with char representation

View File

@ -27,10 +27,8 @@
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *^*/ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *^*/
namespace Pluie namespace Pluie.Yaml
{ {
namespace Yaml
{
const string YAML_VERSION = "1.2"; const string YAML_VERSION = "1.2";
const string YAML_VALA_PREFIX = "v"; const string YAML_VALA_PREFIX = "v";
const string YAML_VALA_DIRECTIVE = "tag:pluie.org,2018:vala/"; 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); 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); 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); 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); if (Pluie.Yaml.DEBUG && msg != null) of.echo (msg);
} }
@ -441,5 +439,4 @@ namespace Pluie
h.substring (20) h.substring (20)
); );
} }
}
} }

View File

@ -31,11 +31,11 @@
DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
lib="pluie-yaml-0.5" lib="pluie-yaml-0.5"
cd $DIR 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 if [ $? -eq 0 ]; then
rm doc/*.png rm doc/*.png
cp resources/doc-scripts.js ./doc/scripts.js cp resources/doc-scripts.js ./doc/scripts.js
cp resources/doc-style.css ./doc/style.css cp resources/doc-style.css ./doc/style.css
rm $lib.tar.gz #~ rm $lib.tar.gz
tar -czvf $lib.tar.gz doc/ #~ tar -czvf $lib.tar.gz doc/
fi fi