GNOME.org
 

[gxml/gxml-0-4] Adding Mallard documentation for Serializable

commit e0a20b0c96fb525a0dcba97ffbd09831ad46d0fc
Author: Daniel Espinosa <esodan gmail com>
Date:   Thu Sep 18 19:28:20 2014 -0500

    Adding Mallard documentation for Serializable

 Makefile.am                               |    2 +-
 configure.ac                              |   32 ++++++--
 docs/Makefile.am                          |  133 ++---------------------------
 docs/mallard/C/Makefile.am                |   33 +++++++
 docs/mallard/C/gxml-serializable.page     |   57 ++++++++++++
 docs/mallard/C/index.page                 |   25 ++++++
 docs/mallard/Makefile.am                  |   10 ++
 docs/valadoc/Makefile.am                  |  126 +++++++++++++++++++++++++++
 docs/{ => valadoc}/wiki/concepts.valadoc  |    0
 docs/{ => valadoc}/wiki/debugging.valadoc |    0
 docs/{ => valadoc}/wiki/glossary.valadoc  |    0
 gxml/Serializable.vala                    |    2 +-
 12 files changed, 287 insertions(+), 133 deletions(-)
---
diff --git a/Makefile.am b/Makefile.am
index 3f085e7..f3dd6bf 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -7,7 +7,7 @@ ACLOCAL_AMFLAGS = -I m4 ${ACLOCAL_FLAGS}
 # Set up subdirectories to traverse
 SUBDIRS = gxml test po examples
 
-if HAVE_VALADOC
+if ENABLE_DOCS
 SUBDIRS += docs
 endif
 
diff --git a/configure.ac b/configure.ac
index 4309183..85c2c30 100644
--- a/configure.ac
+++ b/configure.ac
@@ -143,11 +143,32 @@ AM_CONDITIONAL([ENABLE_DOCS], [test x$enable_docs = xyes])
 have_valadoc=no
 if test x$enable_docs = xyes; then
   # make sure the library is new enough and the program exists
-  AC_PATH_PROG([VALADOC], [valadoc], [:])
-  AS_IF([test "$VALADOC" != :], have_valadoc=yes)
+  AC_PATH_PROG([VALADOC], [valadoc], [no])
+  if test "x$VALADOC" = "xno";
+  then
+      AC_MSG_RESULT([valadoc documentation not build because not found])
+  else
+      AC_SUBST(VALADOC)
+      have_valadoc="yes"
+  fi
 fi
 AM_CONDITIONAL([HAVE_VALADOC], [test x$have_valadoc = xyes])
 
+dnl Find yelp-build program
+enable_mallard_doc="no"
+if test x$enable_docs = xyes; then
+  AC_PATH_PROG(YELP_BUILD, [yelp-build], [no])
+  if test "x$YELP_BUILD" = "xno";
+  then
+      AC_MSG_RESULT([Mallard documentation not build because yelp-build has not been found])
+  else
+      YELP_HELP_INIT
+      AC_SUBST(YELP_BUILD)
+      enable_mallard_doc="yes"
+  fi
+fi
+AM_CONDITIONAL(ENABLE_MALLARD_DOC, [test "$enable_mallard_doc" = "yes"])
+
 debug=no
 AC_ARG_ENABLE(debug,
        AS_HELP_STRING([--enable-debug], [Enable Debug options [default=no]]),
@@ -155,10 +176,6 @@ AC_ARG_ENABLE(debug,
 
 AM_CONDITIONAL(DEBUG, [test $debug = yes])
 
-if test "x$enable_docs" = "xyes" -a "x$have_valadoc" != "xyes"; then
-  AC_MSG_ERROR([Doc building requested for valadoc but not installed.])
-fi
-
 # Check for GObject Introspection
 GOBJECT_INTROSPECTION_CHECK([1.32.0])
 
@@ -209,6 +226,9 @@ test/test_out_path_expected.xml
 test/test_out_stream_expected.xml
 test/test_with_ns.xml
 docs/Makefile
+docs/valadoc/Makefile
+docs/mallard/Makefile
+docs/mallard/C/Makefile
 examples/Makefile
 examples/c/Makefile
 examples/js/Makefile
diff --git a/docs/Makefile.am b/docs/Makefile.am
index 3c6a919..3c31eb7 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -1,125 +1,8 @@
-# inspired by folks' documentation Makefile.am
-
-# distclean_dirs? 
-# phony_deps?
-distclean_dirs = \
-       gxml \
-       gtk-doc \
-       $(NULL)
-
-phony_deps = \
-       gxml-doc \
-       gxml-gtk-doc \
-       $(NULL)
-
-gxml_wiki_pages = \
-       concepts \
-       glossary \
-       debugging \
-       $(NULL)
-
-# Huh, gxml_wiki_files isn't defined for a while down below
-EXTRA_DIST = $(gxml_wiki_files)
-
-
-
-# ---------------------------------------------------------
-
-gxmldocdir=$(datadir)/devhelp/references/gxml
-gxmlimgdir=$(datadir)/devhelp/references/gxml/img
-
-gxmlgtkdocdir=$(datadir)/gtk-doc/html/gxml
-
-common_doc_files = \
-       *.css \
-       *.png \
-       *.js \
-       index.htm \
-       *.html \
-       $(NULL)
-
-gxmldoc_DATA = \
-       gxml/GXml/GXml.devhelp2 \
-       $(addprefix gxml/GXml/,$(common_doc_files)) \
-       $(NULL)
-
-gxmlgtkdoc_DATA = gtk-doc/gxml/html/*
-
-# gxmlimg_DATA = gxml/gxml/img/*.png
-
-# $(gxmldoc_DATA) ($gxmlimg_DATA): gxml-doc
-$(gxmldoc_DATA): gxml-doc
-$(gxmlgtkdoc_DATA): gxml-gtk-doc
-
-
-# -------------------------------------------------------
-
-valadoc_flags = \
-       --force \
-       --package-name GXml \
-       --package-version $(PACKAGE_VERSION) \
-       $(NULL)
-
-#      $(top_srcdir)/gxml/internal.vala 
-gxml_doc_files_blacklist = \
-       $(NULL)
-
-# this expands the list of files, so we can filter out elements
-gxml_doc_files_all = \
-       $(wildcard $(top_srcdir)/gxml/*.vala) \
-       $(NULL)
-
-gxml_wiki_files = \
-       $(addprefix wiki/,$(addsuffix .valadoc,$(gxml_wiki_pages))) \
-       $(NULL)
-
-# TODO: Fix this.  Sorting done to "work around the native doclet portino of bgo#662784" - folks
-gxml_doc_files = \
-       $(sort \
-       $(filter-out $(gxml_doc_files_blacklist),$(gxml_doc_files_all)))
-
-# todo: find out what dependencies I want/need to set
-gxml_doc_deps = \
-       gio-2.0 \
-       gee-0.8 \
-       libxml-2.0 \
-       $(NULL)
-
-valadoc_flags_gxml = \
-       $(valadoc_flags) \
-       -X $(top_srcdir)/gxml/gxml.h \
-       $(addprefix --pkg=,$(gxml_doc_deps)) \
-       --vapidir=$(top_srcdir)/gxml \
-       --vapidir=$(top_srcdir)/vapi \
-       --wiki=$(top_srcdir)/docs/wiki \
-       $(gxml_doc_files) \
-       $(NULL)
-
-
-#      $(AM_V_GEN)$(VALADOC) 
-gxml-doc: $(gxml_doc_files) $(gxml_wiki_files)
-       $(VALADOC) \
-               -o gxml/ \
-               --doclet=devhelp \
-               $(valadoc_flags_gxml) \
-               $(NULL)
-
-# TODO: need to figure out how to not rely on -0.2 in this Makefile.am
-# AM_V_GEN: what does it do?  It appears to prettify output but also obscure errors :D
-#      $(AM_V_GEN)$(VALADOC)
-gxml-gtk-doc: $(gxml_doc_files) $(gxml_wiki_files)
-       $(VALADOC) \
-               -o gtk-doc/gxml \
-               --doclet=gtkdoc \
-               $(valadoc_flags_gxml) \
-               $(NULL)
-
-.PHONY: $(phony_deps)
-
-distclean:
-       rm -rf $(distclean_dirs) Makefile
-
-# Hack, because I don't know how to make the other ones targets :D
-# all: gxml-gtk-doc gxml-doc
-
--include $(top_srcdir)/git.mk
+SUBDIRS=
+if ENABLE_MALLARD_DOC
+  SUBDIRS += mallard
+endif
+
+if HAVE_VALADOC
+  SUBDIRS += valadoc
+endif
diff --git a/docs/mallard/C/Makefile.am b/docs/mallard/C/Makefile.am
new file mode 100644
index 0000000..3682538
--- /dev/null
+++ b/docs/mallard/C/Makefile.am
@@ -0,0 +1,33 @@
+
+sources = \
+       index.page \
+       gxml-serializable.page
+
+JS_FILES= \
+       C.css \
+       jquery.js \
+       jquery.syntax.js \
+       jquery.syntax.brush.clang.js \
+       jquery.syntax.layout.yelp.js \
+       jquery.syntax.core.js \
+       yelp.js \
+       yelp-note-tip.png
+
+$(JS_FILES): htmldoc
+
+all: htmldoc
+
+htmldoc: $(sources)
+       $(YELP_BUILD) html $^
+
+#htmldocdir=$(HTML_DIR)/gxml-$(API_VERSION)
+
+#htmldoc_DATA = \
+#      $(sources:.page=.html) \
+#      $(JS_FILES)
+
+$(sources:.page=.html): htmldoc
+
+CLEANFILES = \
+       $(sources:.page=.html) \
+       $(JS_FILES)
diff --git a/docs/mallard/C/gxml-serializable.page b/docs/mallard/C/gxml-serializable.page
new file mode 100644
index 0000000..30d94d5
--- /dev/null
+++ b/docs/mallard/C/gxml-serializable.page
@@ -0,0 +1,57 @@
+<page xmlns="http://projectmallard.org/1.0/";
+        type="topic" id="gxml-serializable">
+
+  <info>
+    <revision pkgversion="0.4" version="0.1" date="2014-09-18" status="incomplete" />
+    <credit type="author">
+      <name>Daniel Espinosa</name>
+      <email>esodan gmail com</email>
+    </credit>
+    <license>
+      <p>Creative Commons Share Alike 3.0</p>
+    </license>
+    <link type="topic" xref="index" />
+  </info>
+
+  <title>Serializable Interface</title>
+  <p>Implementors of this interface, could define or override the way you want to represent your class in a 
XML file.</p>
+  <section id="gxml-serializable-properties">
+               <title>Serializable properties</title>
+               <p>You can get control on class's properties to be serialized to XML. Allowing to provide 
ones, storing runtime information and ones to be stored in XML. By default, all object's properties are 
serialized. In order to skip properties from serialization process you must add its canonical name as key and 
its canonical name as value, to <code>ignored_serializable_properties</code> store.</p>
+               <p>Implementator must use <code>ignored_serializable_properties</code> property to check if a 
property should be serialized. This allows to dynamically remove, on convenience, properties on 
serialization. You can use <code>list_serializable_properties()</code> method as a convenient function, using 
its default implementation, or even override it at your convenience to automate dynamic serializable 
properties at run time; just make sure to skip the unwanted properties.</p>
+               <p>There are more methods to avoid properties serialization, like to override 
<code>init_properties</code> default implementation. It stores all <code>Serializale</code>'s properties to 
be ignored by default; you must ensure to initialize correctly, by calling 
<code>default_init_properties()</code> method before any other code in your overrided method.</p>
+       <section id="gxml-serializable-unknown_properties">
+  <title>Unknown XML elements</title>
+       <p>XML allows great flexibility, providing different ways to represent the same information. This is 
a problem when you try to deserialize them.</p>
+       <p>In order to deserialize correctly, you must create your XML, both by serializing a 
<code>Serializable</code> object or by hand writing. By using the former, you can add extra information, like 
nodes or properties, but most of them could be ignored or lost on deserialization/serialization process. To 
avoid data lost, you can override <code>get_enable_unknown_serializable_property ()</code> method in order to 
return true, your implementation or the ones in GXml, will store all unknown properties and nodes on 
deserialization and must serialize again back to the XML file. Even you are allowed to get this unknown 
objects by iterating on <code>unknown_serializable_property</code> hash table.</p>
+       </section>
+  <section id="gxml-serializable-property-name">
+  <title>Property's name</title>
+  <p>When serialize a class property, by default it uses its name given  on class declaration, but is less 
common to see XML node mproperties with name like <code>your_property</code>, but more common is to use 
<code>YourProperty</code>. In order to use this kind of names, your implementation should use properties' 
nick name and override <code>property_use_nick()</code> method to return true. This should instruct your code 
to use this method to use property's nick name. This is the default in GXml default implementations.</p>
+  <p>In order to set node's name, you should override <code>node_name()</code> method.</p>
+  </section>
+  </section>
+  <section id="gxml-serializable-node-contents">
+  <title>XML node's content</title>
+  <p>By default GXml's implementations doesn't deseriaze/serialize XML node contents. In order to enable it, 
you must override <code>serialize_use_xml_node_value()</code> method to return true and store XML node's 
content to <code>serialized_xml_node_value</code> property.</p>
+  <p>Implementors could set up methods to provide a clean easy to use API to set nodes contents. In most 
cases, users would like to set a value through a getter or setter or through a property in the class. If you 
use a property, you should add it to <code>ignored_serializable_properties</code> in order to see its value 
in a XML node property.</p>
+  </section>
+  <section id="gxml-serializable-node-name">
+  <title>XML node name</title>
+  <p>On serialization XML node's name could be set to use a prety one. By default, node's name is the class 
name; becareful because name could be <code>GXmlSerializable</code>, while may you prefer to use just 
'Serializable'.</p>
+  <p>In order to set node's name, you should override <code>node_name()</code> method.</p>
+  </section>
+  <section id="gxml-serializable-serialize">
+  <title>Serialize</title>
+  <p><code>Serializable</code> interface allows you to implement your own <code>serialize()</code> method. 
Your implementation should take a <code>GXml.Node</code> and serialize over it. Given <code>GXml.Node</code>, 
could be an <code>GXml.Element</code> or a <code>GXml.Document</code>, your implementaiton should take care 
about this and return XML nodes representing your class object.</p>
+  </section>
+  <section id="gxml-serializable-serialize-property">
+  <title>Serialize a property</title>
+  <p><code>Serializable</code> interface allows you to implement your own <code>serialize_property()</code> 
method. Your implementation should take a <code>GXml.Element</code> to serialize on your property. Your 
implementation could detect the property to serialize and get its value, from given 
<code>GLib.ParamSpec</code>. Your serialization could be add a <code>GXml.Attr</code> or child 
<code>GXml.Element</code> to the given <code>GXml.Element</code> or set a contents to it; its your choice.</p>
+  </section>
+  <section id="gxml-serializable-deserialize">
+  <title>Deserialize</title>
+  <p><code>Serializable</code> interface allows you to implement your own <code>deserialize()</code> method. 
Your implementation should take a <code>GXml.Node</code> and deserialize from it. Given 
<code>GXml.Node</code>, could be an <code>GXml.Element</code> or a <code>GXml.Document</code>, your 
implementaiton should take care about this and return XML nodes representing your class object.</p>
+  <p>Your implementation could take <code>GXml.Element</code>'s name to detect the property to set up or 
detect the root element in a <code>GXml.Document</code> to use. Then you can iterate over all node's 
properties and set up your object properties; you can use <code>gvalue_to_string()</code> to transform most 
common value types from string to the required value's type.</p>
+  </section>
+</page>
diff --git a/docs/mallard/C/index.page b/docs/mallard/C/index.page
new file mode 100644
index 0000000..54cfa73
--- /dev/null
+++ b/docs/mallard/C/index.page
@@ -0,0 +1,25 @@
+<page xmlns="http://projectmallard.org/1.0/";
+       type="guide" id="index">
+
+  <info>
+    <revision pkgversion="0.4" version="0.1" date="2014-09-18" status="incomplete"/>
+    <credit type="author">
+      <name>Daniel Espinosa</name>
+      <email>esodan gmail com</email>
+    </credit>
+    <license>
+      <p>Creative Commons Share Alike 3.0</p>
+    </license>
+  </info>
+
+  <title>
+    GXml Serialization Framework Manual
+  </title>
+  <p>
+  This guide provides examples and applications of GXml's Serialization Framework.
+  </p>
+  <p>GXml Serialization Framework allows <code>GLib.Object</code> objects to be serialized to XML files.</p>
+  <p>It has a <code>Serializable</code> interface to be implemented by a <code>GLib.Object</code> class, 
allowing great flexibility on how the object must be represented in XML format.</p>
+  <p>Today GXml have two implementations, one of them is <code>SerializableObjectModel</code>, using a model 
where each object is a XML node and a each object's property is a XML node property.</p>
+  <p>Serialization Framework have containers implementations, allowing to store <code>Serializable</code> 
objects in arrays, hash tables and multikey stores.</p>
+</page>
diff --git a/docs/mallard/Makefile.am b/docs/mallard/Makefile.am
new file mode 100644
index 0000000..5c42547
--- /dev/null
+++ b/docs/mallard/Makefile.am
@@ -0,0 +1,10 @@
+
+sources = \
+       index.page \
+       gxml-serializable.page
+
+ YELP_HELP_RULES@
+HELP_ID=gxml
+HELP_FILES=$(sources)
+HELP_MEDIA=
+
diff --git a/docs/valadoc/Makefile.am b/docs/valadoc/Makefile.am
new file mode 100644
index 0000000..31f767c
--- /dev/null
+++ b/docs/valadoc/Makefile.am
@@ -0,0 +1,126 @@
+# inspired by folks' documentation Makefile.am
+
+# distclean_dirs? 
+# phony_deps?
+distclean_dirs = \
+       gxml \
+       gtk-doc \
+       $(NULL)
+
+phony_deps = \
+       gxml-doc \
+       gxml-gtk-doc \
+       $(NULL)
+
+gxml_wiki_pages = \
+       concepts \
+       glossary \
+       debugging \
+       $(NULL)
+
+
+# Huh, gxml_wiki_files isn't defined for a while down below
+EXTRA_DIST = $(gxml_wiki_files)
+
+
+
+# ---------------------------------------------------------
+
+gxmldocdir=$(datadir)/devhelp/references/gxml
+gxmlimgdir=$(datadir)/devhelp/references/gxml/img
+
+gxmlgtkdocdir=$(datadir)/gtk-doc/html/gxml
+
+common_doc_files = \
+       *.css \
+       *.png \
+       *.js \
+       index.htm \
+       *.html \
+       $(NULL)
+
+gxmldoc_DATA = \
+       gxml/GXml/GXml.devhelp2 \
+       $(addprefix gxml/GXml/,$(common_doc_files)) \
+       $(NULL)
+
+gxmlgtkdoc_DATA = gtk-doc/gxml/html/*
+
+# gxmlimg_DATA = gxml/gxml/img/*.png
+
+# $(gxmldoc_DATA) ($gxmlimg_DATA): gxml-doc
+$(gxmldoc_DATA): gxml-doc
+$(gxmlgtkdoc_DATA): gxml-gtk-doc
+
+
+# -------------------------------------------------------
+
+valadoc_flags = \
+       --force \
+       --package-name GXml \
+       --package-version $(PACKAGE_VERSION) \
+       $(NULL)
+
+#      $(top_srcdir)/gxml/internal.vala 
+gxml_doc_files_blacklist = \
+       $(NULL)
+
+# this expands the list of files, so we can filter out elements
+gxml_doc_files_all = \
+       $(wildcard $(top_srcdir)/gxml/*.vala) \
+       $(NULL)
+
+gxml_wiki_files = \
+       $(addprefix wiki/,$(addsuffix .valadoc,$(gxml_wiki_pages))) \
+       $(NULL)
+
+# TODO: Fix this.  Sorting done to "work around the native doclet portino of bgo#662784" - folks
+gxml_doc_files = \
+       $(sort \
+       $(filter-out $(gxml_doc_files_blacklist),$(gxml_doc_files_all)))
+
+# todo: find out what dependencies I want/need to set
+gxml_doc_deps = \
+       gio-2.0 \
+       gee-0.8 \
+       libxml-2.0 \
+       $(NULL)
+
+valadoc_flags_gxml = \
+       $(valadoc_flags) \
+       -X $(top_srcdir)/gxml/gxml.h \
+       $(addprefix --pkg=,$(gxml_doc_deps)) \
+       --vapidir=$(top_srcdir)/gxml \
+       --vapidir=$(top_srcdir)/vapi \
+       --wiki=$(top_srcdir)/docs/wiki \
+       $(gxml_doc_files) \
+       $(NULL)
+
+
+#      $(AM_V_GEN)$(VALADOC) 
+gxml-doc: $(gxml_doc_files) $(gxml_wiki_files)
+       $(VALADOC) \
+               -o gxml/ \
+               --doclet=devhelp \
+               $(valadoc_flags_gxml) \
+               $(NULL)
+
+# TODO: need to figure out how to not rely on -0.2 in this Makefile.am
+# AM_V_GEN: what does it do?  It appears to prettify output but also obscure errors :D
+#      $(AM_V_GEN)$(VALADOC)
+gxml-gtk-doc: $(gxml_doc_files) $(gxml_wiki_files)
+       $(VALADOC) \
+               -o gtk-doc/gxml \
+               --doclet=gtkdoc \
+               $(valadoc_flags_gxml) \
+               $(NULL)
+
+.PHONY: $(phony_deps)
+
+distclean:
+       rm -rf $(distclean_dirs) Makefile
+
+# Hack, because I don't know how to make the other ones targets :D
+# all: gxml-gtk-doc gxml-doc
+
+-include $(top_srcdir)/git.mk
diff --git a/docs/wiki/concepts.valadoc b/docs/valadoc/wiki/concepts.valadoc
similarity index 100%
rename from docs/wiki/concepts.valadoc
rename to docs/valadoc/wiki/concepts.valadoc
diff --git a/docs/wiki/debugging.valadoc b/docs/valadoc/wiki/debugging.valadoc
similarity index 100%
rename from docs/wiki/debugging.valadoc
rename to docs/valadoc/wiki/debugging.valadoc
diff --git a/docs/wiki/glossary.valadoc b/docs/valadoc/wiki/glossary.valadoc
similarity index 100%
rename from docs/wiki/glossary.valadoc
rename to docs/valadoc/wiki/glossary.valadoc
diff --git a/gxml/Serializable.vala b/gxml/Serializable.vala
index 6f6ab94..e334780 100644
--- a/gxml/Serializable.vala
+++ b/gxml/Serializable.vala
@@ -100,7 +100,7 @@ namespace GXml {
     /**
      * Serialize this object.
      *
-     * @doc an { link GXml.Document} object to serialise to 
+     * @doc an { link GXml.Document} object to serialize to 
      *
      * This method must call serialize_property() recursivally on all properties
      * to serialize.
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]