GNOME.org
 

[libgda] Added documantation for developers about GObject Introspection in GDA

commit 1d73d3645401527ea45133b4eabb8db01418da01
Author: Daniel Espinosa <despinosa src gnome org>
Date:   Mon Jan 23 10:37:53 2012 -0600

    Added documantation for developers about GObject Introspection in GDA

 doc/mallard/gobject-introspection/about-gi.page    |   58 ++++++++++++++++++++
 .../gobject-introspection/api-stability.page       |   46 ++++++++++++++++
 .../gobject-introspection/distribution.page        |   26 +++++++++
 doc/mallard/gobject-introspection/gda-vala.page    |   44 +++++++++++++++
 .../gobject-introspection/gir-generation.page      |   30 ++++++++++
 doc/mallard/gobject-introspection/gir-update.page  |   30 ++++++++++
 doc/mallard/gobject-introspection/index.page       |   22 ++++++++
 doc/mallard/gobject-introspection/problems.page    |   22 ++++++++
 8 files changed, 278 insertions(+), 0 deletions(-)
---
diff --git a/doc/mallard/gobject-introspection/about-gi.page b/doc/mallard/gobject-introspection/about-gi.page
new file mode 100644
index 0000000..f35c7f9
--- /dev/null
+++ b/doc/mallard/gobject-introspection/about-gi.page
@@ -0,0 +1,58 @@
+<page xmlns="http://projectmallard.org/1.0/";
+	 type="topic" id="about-gi">
+
+  <info>
+    <revision pkgversion="5.2" version="0.1" date="2012-01-18" status="incomplete"/>
+    <credit type="author">
+      <name>Daniel Espinosa</name>
+      <email>despinosa src gnome org</email>
+    </credit>
+    <license>
+      <p>Creative Commons Share Alike 3.0</p>
+    </license>
+    <link type="topic" xref="index" />
+  </info>
+
+  <title>
+    What is GObject Introspection?
+  </title>
+  <section id="Description">
+  <title>Description</title>
+  <p>
+  GObject Introspection (GI) is a set of tools to generate meta-information about the API mainly for GLib/GObject
+  based libraries. It generates two files one in XML and one in a binary format. Most of the GI meta-information is
+  detected automatically by scanning C source code and gtk-doc annotations.
+  </p>
+  <note style="tip">
+  <p>GDA is mainly written in C with gtk-doc. Developers has appended lot of annotations to gtk-doc documentation
+  in order to allow GI to detect correctly all meta-data.</p>
+  </note>
+  <p>
+  These meta-information is used by others to get access to GDA's methods and objects, using different
+  languages other than C, like Python, JavaScript and others with GI support.
+  </p>
+  <p>
+  The XML  and binary file format are Gda-[MajorVersion]-0.gir and Gda-[MajorVersion]-0.typelib respectively, where 
+  [MajorVersion] is set to current major version in GDA. For example Gda-5.0.gir, for GDA version 5.x series.
+  </p>
+  <note style="tip">
+  <p>
+  GDA generates these files for you at build time.
+  </p>
+  </note>
+  <note style="tip">
+	  <p>
+	  In this guide we use GIR to refer XML file with extension .gir and TYPELIB for binary format with extension .typelib
+	  </p>
+  </note>
+  </section>
+  <section>
+  <title>Benefits</title>
+  <p>
+  Given access to latest API to C based libraries, to high level languages allows to create powerful applications in less time. Once GDA release a minor release with your new fantastic features including new methods to existing objects or new ones, by updating GI metadata you will give any application to get access to them.
+  </p>
+  <p>
+  If you are developing a web page using Python, you can get new GDA's features as soon as it is installed in your system with its updated GI metadata.
+  </p>
+  </section>
+</page>
diff --git a/doc/mallard/gobject-introspection/api-stability.page b/doc/mallard/gobject-introspection/api-stability.page
new file mode 100644
index 0000000..daec1ce
--- /dev/null
+++ b/doc/mallard/gobject-introspection/api-stability.page
@@ -0,0 +1,46 @@
+<page xmlns="http://projectmallard.org/1.0/";
+	 type="topic" id="api-stability">
+
+  <info>
+    <revision pkgversion="5.2" version="0.1" date="2012-01-18" status="incomplete" />
+    <credit type="author">
+      <name>Daniel Espinosa</name>
+      <email>despinosa src gnome org</email>
+    </credit>
+    <license>
+      <p>Creative Commons Share Alike 3.0</p>
+    </license>
+    <links type="section" />
+    <link type="topic" xref="index" />
+  </info>
+  <title>API stability and GI</title>
+  <section id="api-stability-introduction">
+   <title>Introduction</title> 
+  <p>
+  In GDA, stable versions are numbered by even numbers in minor releases: 5.2 is an stable release. API must be
+  stable along a major release, this mean that any software compiled and running using a 5.2 version must keep 
+  compling and running in any later version.
+  </p>
+  <p>
+  This must be true even for bindings using GObject Introspection. Before to make a release you must check that your
+  modifications will not make API breaks.
+  </p>
+    
+  </section>
+    
+  <section id="api-stability-breaks">
+  <title>How to avoid API breaks using GIR</title>
+    <p>
+  When GDA is compiled you must check GIR changes. You must read http://live.gnome.org/GObjectIntrospection/Annotations in order to know the effect for each annotation you made. GIR format is documented at http://developer.gnome.org/gi/stable/gi-gir.html
+  </p>
+  <p>You must check at least:</p>
+  <steps>
+  	<item>No Objects or methods has been deleted or renamed</item>
+  	<item>Meta data just fix issues, no function names, nor number and type of parameters</item>
+  	<item> </item>
+  	<item> </item>
+  	<item> </item>
+  	<item> </item>
+  </steps>
+  </section>
+</page>
diff --git a/doc/mallard/gobject-introspection/distribution.page b/doc/mallard/gobject-introspection/distribution.page
new file mode 100644
index 0000000..299aee7
--- /dev/null
+++ b/doc/mallard/gobject-introspection/distribution.page
@@ -0,0 +1,26 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      xmlns:e="http://projectmallard.org/experimental/";
+      id="distribution">
+
+  <info>
+    <revision pkgversion="5.2" version="0.1" date="2012-01-18" status="incomplete">
+      <!--
+      <e:review by="despinosa src gnome org" date="2012-01-18" status="incomplete"/>
+      -->
+    </revision>
+    <credit type="author">
+      <name>Daniel Espinosa</name>
+      <email>despinosa src gnome org</email>
+    </credit>
+    <license>
+      <p>Creative Commons Share Alike 3.0</p>
+    </license>
+    <link type="topic" xref="index" />
+  </info>
+
+  <title>
+    Distributing GI Information
+  </title>
+  
+  <p>You must check at least:</p>
+</page>
diff --git a/doc/mallard/gobject-introspection/gda-vala.page b/doc/mallard/gobject-introspection/gda-vala.page
new file mode 100644
index 0000000..577bda6
--- /dev/null
+++ b/doc/mallard/gobject-introspection/gda-vala.page
@@ -0,0 +1,44 @@
+<page xmlns="http://projectmallard.org/1.0/";
+	 type="topic" id="gda-vala">
+
+  <info>
+    <revision pkgversion="5.2" version="0.1" date="2012-01-18" status="incomplete" />
+    <credit type="author">
+      <name>Daniel Espinosa</name>
+      <email>despinosa src gnome org</email>
+    </credit>
+    <license>
+      <p>Creative Commons Share Alike 3.0</p>
+    </license>
+    <link type="topic" xref="index" />
+  </info>
+
+  <title>
+    Vala and GDA
+  </title>
+  
+  <p>
+  In GDA, stable versions are numbered by even numbers in minor releases: 5.2 is an stable release. API must be
+  stable along a major release, this mean that any software compiled and running using a 5.2 version must keep 
+  compling and running in any later version.
+  </p>
+  <p>
+  This must be true even for bindings using GObject Introspection. Before to make a release you must check that your
+  modifications will not make API breaks.
+  </p>
+  <subtitle>
+  How to avoid API breaks using GIR
+  </subtitle>
+  <p>
+  When GDA is compiled you must check GIR changes. You must read http://live.gnome.org/GObjectIntrospection/Annotations in order to know the effect for each annotation you made. GIR format is documented at http://developer.gnome.org/gi/stable/gi-gir.html
+  </p>
+  <p>You must check at least:</p>
+  <list>
+  	<item>No Objects or methods has been deleted or renamed</item>
+  	<item>Meta data just fix issues, no function names, nor number and type of parameters</item>
+  	<item> </item>
+  	<item> </item>
+  	<item> </item>
+  	<item> </item>
+  </list>
+</page>
diff --git a/doc/mallard/gobject-introspection/gir-generation.page b/doc/mallard/gobject-introspection/gir-generation.page
new file mode 100644
index 0000000..08d4e17
--- /dev/null
+++ b/doc/mallard/gobject-introspection/gir-generation.page
@@ -0,0 +1,30 @@
+<page xmlns="http://projectmallard.org/1.0/";
+	 type="topic" id="gir-generation">
+
+  <info>
+    <revision pkgversion="5.2" version="0.1" date="2012-01-18" status="incomplete"/>
+    <credit type="author">
+      <name>Daniel Espinosa</name>
+      <email>despinosa src gnome org</email>
+    </credit>
+    <license>
+      <p>Creative Commons Share Alike 3.0</p>
+    </license>
+    <link type="topic" xref="index" />
+  </info>
+
+  <title>
+    How to generate GI information
+  </title>
+  <section id="gi-generation-general">
+  <title>General</title>
+  <p>
+  GDA has support for GObject Introspection (GI) since 4.2.x at build time. Always GI is found installed in your
+  system, Autotools automatically generates GIR and TYPELIB files for you. After success build with <code>make</code> you can <code>make install</code> to install these files and you are ready to use your favorite language.
+  </p>
+  </section>
+  <section id="gi-generation-autotools">
+  
+  </section>
+  
+</page>
diff --git a/doc/mallard/gobject-introspection/gir-update.page b/doc/mallard/gobject-introspection/gir-update.page
new file mode 100644
index 0000000..2c171e6
--- /dev/null
+++ b/doc/mallard/gobject-introspection/gir-update.page
@@ -0,0 +1,30 @@
+<page xmlns="http://projectmallard.org/1.0/";
+	 type="topic" id="gir-update">
+
+  <info>
+    <revision pkgversion="5.2" version="0.1" date="2012-01-18" status="incomplete" />
+    <credit type="author">
+      <name>Daniel Espinosa</name>
+      <email>despinosa src gnome org</email>
+    </credit>
+    <license>
+      <p>Creative Commons Share Alike 3.0</p>
+    </license>
+    <link type="topic" xref="index" />
+  </info>
+
+  <title>
+    How to update GI information
+  </title>
+  
+  <p>
+  Once GDA developers have approved new API and include it in GDA in the form of header and C source code it can be detected by GI and parsed to generate updated GIR/TYPELIB files. This allows other language to get access to new awesome features in GDA.
+  </p>
+  <note style="tip">
+  <p><code>libgda/Makefile.am</code> have all files to be scanned by GI. If you just modify them your new API will be detected and added automatically. If you create a new object, with a .c file and a new header, you need to add them to the list of files to scan.</p>
+  </note>
+  <p>
+  You can update GI meta-data by adding or modifying annotations in gtk-doc. You must check that your changes will
+  keep stable API by verifying generated GIR file.
+  </p>
+</page>
diff --git a/doc/mallard/gobject-introspection/index.page b/doc/mallard/gobject-introspection/index.page
new file mode 100644
index 0000000..c69b2f4
--- /dev/null
+++ b/doc/mallard/gobject-introspection/index.page
@@ -0,0 +1,22 @@
+<page xmlns="http://projectmallard.org/1.0/";
+	type="guide" id="index">
+
+  <info>
+    <revision pkgversion="5.2" version="0.1" date="2012-01-20" status="incomplete"/>
+    <credit type="author">
+      <name>Daniel Espinosa</name>
+      <email>despinosa src gnome org</email>
+    </credit>
+    <license>
+      <p>Creative Commons Share Alike 3.0</p>
+    </license>
+  </info>
+
+  <title>
+    GObject Introspection on GDA
+  </title>
+  <p>
+  This guide will shows you how to deal with GObject Introspection (GI) in GDA.
+  </p>
+
+</page>
diff --git a/doc/mallard/gobject-introspection/problems.page b/doc/mallard/gobject-introspection/problems.page
new file mode 100644
index 0000000..8050a61
--- /dev/null
+++ b/doc/mallard/gobject-introspection/problems.page
@@ -0,0 +1,22 @@
+<page xmlns="http://projectmallard.org/1.0/";
+	 type="topic" id="problems">
+
+  <info>
+    <revision pkgversion="5.2" version="0.1" date="2012-01-18" status="incomplete" />
+    <credit type="author">
+      <name>Daniel Espinosa</name>
+      <email>despinosa src gnome org</email>
+    </credit>
+    <license>
+      <p>Creative Commons Share Alike 3.0</p>
+    </license>
+    <link type="topic" xref="index" />
+  </info>
+
+  <title>
+    Common problems
+  </title>
+  
+  <p>
+  </p>
+</page>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]