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
{
/**
* 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@";

View File

@ -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;
/**

View File

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

View File

@ -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
{

View File

@ -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)
{

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
{

View File

@ -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

View File

@ -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

View File

@ -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)
);
}
}
}

View File

@ -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