GNOME.org
 

[gxml: 6/7] Merge branch 'gxml-0-4'

commit 98c0505fbe76805bc523bd8b41c9c83406f3c23e
Merge: a3e76fa c7aa6ce
Author: Daniel Espinosa <esodan gmail com>
Date:   Wed Nov 12 11:54:37 2014 -0600

    Merge branch 'gxml-0-4'
    
    Conflicts:
        configure.ac
        docs/valadoc/Makefile.am
        gxml/Document.vala
        gxml/Element.vala
        gxml/Enumeration.vala
        gxml/Node.vala
        gxml/Serializable.vala

 NEWS                     |    7 +++
 docs/valadoc/Makefile.am |  110 ++++++++++++++++++++++++++++++++++++++++++++-
 gxml/Document.vala       |    8 ++--
 gxml/Element.vala        |    3 +-
 gxml/Enumeration.vala    |   23 +++++----
 gxml/Node.vala           |    4 +-
 gxml/Serializable.vala   |   88 ++++++++++--------------------------
 7 files changed, 160 insertions(+), 83 deletions(-)
---
diff --cc NEWS
index 33bf92e,33bf92e..7ac4f8e
--- a/NEWS
+++ b/NEWS
@@@ -1,4 -1,4 +1,11 @@@
  =============
++Version 0.4.2
++=============
++- Fixes to Vala bindings documentation for DevHelp (Daniel Espinosa)
++- Preview of gtk-doc and documented GIR generation (Daniel Espinosa)
++
++
++=============
  Version 0.4.1
  =============
  - Fixed compile with Vala 0.26 (Daniel Espinosa)
diff --cc docs/valadoc/Makefile.am
index c546597,9155afe..a66aac2
--- a/docs/valadoc/Makefile.am
+++ b/docs/valadoc/Makefile.am
@@@ -1,16 -1,117 +1,120 @@@
- -include $(top_srcdir)/git.mk
- CLEANFILES=
- SUBDIRS=
+ # 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/valadoc/wiki \
+       $(NULL)
+ 
+ 
+ #     $(AM_V_GEN)$(VALADOC) 
+ gxml-doc:
+       $(VALADOC) -o gxml/ --doclet=devhelp $(valadoc_flags_gxml) $(top_srcdir)/gxml/*.vala
+ 
+ # 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:
+       $(VALADOC) -o gtk-doc/gxml --doclet=gtkdoc $(valadoc_flags_gxml) $(top_srcdir)/gxml/*.vala
  
 -.PHONY: $(phony_deps)
 +if ENABLE_DEVHELP_DOCS
 +SUBDIRS+=devhelp
 +endif
  
 -distclean:
 -      rm -rf $(distclean_dirs) Makefile
 +if ENABLE_GTK_DOCS
 +SUBDIRS+=gtk-doc
 +endif
  
 -# Hack, because I don't know how to make the other ones targets :D
 -# all: gxml-gtk-doc gxml-doc
 +if ENABLE_GIR_DOCS
 +SUBDIRS+=gir-docs
 +endif
  
 --include $(top_srcdir)/git.mk
diff --cc gxml/Element.vala
index 0cb894b,62f3916..e0291f3
--- a/gxml/Element.vala
+++ b/gxml/Element.vala
@@@ -463,9 -463,9 +463,10 @@@ namespace GXml 
                 * { inheritDoc}
                 *
                 * For { link GXml.Element} this method copy attributes and child nodes
 -               * when @deep is set to { link true}.
 +               * when @deep is set to true.
                 *
-                * @param node could be owned by other { link GXml.Document}.
 -               * { link [node]} could be owned by other { link GXml.Document}.
++               * @param node: could be owned by other { link GXml.Document}.
++               * @param deep: copy child nodes if true.
                 */
                public override bool copy (ref Node node, bool deep = false)
                                    requires (node is Element)
diff --cc gxml/Enumeration.vala
index 383a763,45933de..cd40cb5
--- a/gxml/Enumeration.vala
+++ b/gxml/Enumeration.vala
@@@ -130,7 -120,10 +133,7 @@@ namespace GXml 
                 * 
                 * Returns: an array of { link GLib.EnumValue} representing an enumeration.
                 * 
-                * @param enumeration a { link GLib.Type} of type { link GLib.Type.ENUM}
+                * @param enumeration: a { link GLib.Type} of type { link GLib.Type.ENUM}
 -               * @param val: a string to parse an enum value of type @enumeration.
 -               * @param camelcase: makes to returns value's nick name in { link GLib.EnumClass}
 -               * as camel case representation. If @use_nick is set this take no effect.
                 */
                public static unowned EnumValue[] to_array (Type enumeration)
                                               requires (enumeration.is_a (Type.ENUM))
diff --cc gxml/Serializable.vala
index 00b0f16,a2d575e..e39b2cc
--- a/gxml/Serializable.vala
+++ b/gxml/Serializable.vala
@@@ -86,89 -70,48 +86,63 @@@ namespace GXml 
       *
       * By default no contents is serialized/deseralized. Implementors must implement
       * { link Serializable.serialize_use_xml_node_value} function returning
 -     * { link true} in order to use this property.
 +     * true in order to use this property.
       *
       * This property is ignored by default. Implementors must implement
-      * { link serialize_use_xml_node_value} to return true and add a
+      * { link serialize_use_xml_node_value} to return { link true} and add a
       * set and get function to get/set this value, in order to use your own API.
       *
       * This property is ignored on serialisation.
       */
      public abstract string?  serialized_xml_node_value { get; protected set; default = null; }
 -    /**
 -     * Used to check { link GXml.Element}'s contents must be deseralized.
 -     *
 -     * By default no contents is serialized/deseralized. Implementors must implement
 -     * this function returning { link true} in order to use { link serialized_xml_node_value}
 -     * property's value in serialization to set { link GXml.Element}'s contents.
 -     *
 +      /**
 +      * Used to check { link GXml.Element}'s contents must be deseralized.
 +      * 
 +      * By default GXml's implementations doesn't deseriaze/serialize XML node contents.
 +      * In order to enable it, you must override { link serialize_use_xml_node_value}
 +      * method to return true and store XML node's content to { link serialized_xml_node_value}
 +      * property.
 +      * 
 +      * 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 { link ignored_serializable_properties} in order to see its value
 +      * in a XML node property.
 +      *
       */
      public abstract bool serialize_use_xml_node_value ();
 -    /**
 -     * Defines the way to set Node name.
 -     */
 +      /**
 +      * Defines the way to set Node name.
 +      */
      public abstract string node_name ();
 -    /**
 -     * Defines the way to set Node's property name, by using
 -     * it's nick instead of default name.
 -     */
 +      /**
 +      * Defines the way to set Node's property name, by using
 +      * it's nick instead of default name.
 +      * 
 +      * When serialize a class property, by default it uses its name given  on class
 +      * declaration, but is less common to see XML node properties with names like
 +      * "your_property", but more common is to use "YourProperty". In order
 +      * to use this kind of names, your implementation should use properties' nick
 +      * name and override { link property_use_nick} 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.
 +      */
      public abstract bool property_use_nick ();
-       /**
-       * Serialize this object.
-       * 
-       * This method must call { link serialize_property} recursivally on all properties
-       * to serialize.
-       * 
-       * { link Serializable} interface allows you to implement your own { link serialize}
-       * method. Your implementation should take a { link GXml.Node} and serialize
-       * over it. Given { link GXml.Node}, could be an { link GXml.Element} or a
-       * { link GXml.Document}, your implementaiton should take care about this and
-       * return XML nodes representing your class object.
-       * 
-       * @param node an { link GXml.Node} object to serialize to.
-       */
+     /**
+      * Serialize this object.
+      * 
+      * This method must call serialize_property() recursivally on all properties
+      * to serialize.
+      * 
+      * @param doc an { link GXml.Document} object to serialize to.
+      */
      public abstract GXml.Node? serialize (GXml.Node node) throws GLib.Error;
  
-       /**
-       * Serialize a property @prop on a { link GXml.Element}.
-       * 
-       * This method is called recursivally by { link serialize} method over all properties
-       * to be serialized.
-       * 
-       * 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 { link ignored_serializable_properties} store.
-       * 
-       * Implementator must use { link ignored_serializable_properties} property to
-       * check if a property should be serialized. This allows to dynamically remove,
-       * on convenience, properties on serialization. You can use { link list_serializable_properties}
-       * 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.
-       * 
-       * There are more methods to avoid properties serialization, like to override
-       * { link init_properties} default implementation. It stores all { link Serializable}'s
-       * properties to be ignored by default; you must ensure to initialize correctly,
-       * by calling { link default_init_properties} method before any other code in
-       * your overrided method.
-       * 
+     /**
+      * Serialize a property @prop on a { link GXml.Element}.
+      * 
+      * This method is called recursivally by { link serialize} method over all properties
+      * to be serialized.
       */
      public abstract GXml.Node? serialize_property (GXml.Element element,
                                                     GLib.ParamSpec prop)
@@@ -594,8 -519,8 +556,8 @@@
       * implementators to provide custome transformations.
       * Call this method before use standard Serializable or implementator ones.
       * 
-      * @param val a { link GLib.Value} to get attribute from
-      * @param str a string describing attribute to deserialize
 -     * @param node a { link GXml.Node} to get attribute from
 -     * @param prop a { link GLib.ParamSpec} describing attribute to deserialize
++     * @param val: a { link GLib.Value} to get attribute from
++     * @param str: a string describing attribute to deserialize
       */
      public abstract bool transform_to_string (GLib.Value val, ref string str)
                                                throws GLib.Error;
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]