grim/gplate

Properly generate the documentation (at least: 100% symbol coverage).

2012-10-02, Michael B. Trausch
3c969ce53aed
Properly generate the documentation (at least: 100% symbol coverage).

I hate to flatten history like this, as this represented by 37 commits
in my local repository. However, I could _not_ get the result to
merge for some reason that I didn't have the time to figure out, so I
flattened it down to a single patch against upstream, and fixed the
resulting diff, and this is that commit.

In a nutshell, this commit:

- gets rid of the SGML template files, as the content that they had
was moved to source code files so that the documentation is closer
to the code, and also because the SGML templates were blocking some
already existing doc-comments in the source code.

- Gets rid of the gplate-sections.txt file, as gtk-doc builds it for
us.

- Gets rid of the gplate.types file. It is generated from scanning
the source code, and adjusted by sed to eliminate things that
gtk-doc won't be able to runtime introspect since they're not
currently "there".

- Hooks the doc/gplates directory into the build system (just
barely). The real work is not even done by CMake, as I couldn't
figure out how to get it to do what I wanted, which leads to...

- The documentation is _actually_ built by doc/gplate/build-docs.sh,
which contains hardcoded values that I could not figure out how to
get CMake to expose certain things. This means that the build
system doesn't actually know jack about the documentation (and this
also means that the documentation won't be installed as part of the
"make install" target, either). (BUT, the documentation is
available and BUILDS!)

While this commit makes things better than they were before the
commit, I would not call this commit overly polished. I fully expect
the shell script to be replaced by something done in/with/via CMake
directly, I just don't know how to do it that way.
/*
* GPlate - GObject based templating library
* Copyright (C) 2007-2012 Gary Kramlich <grim@reaperworld.com>
*
* This library is free software: you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this library. If not, see <http://www.gnu.org/licenses/>.
*/
#ifndef GPLATE_COLLECTION_H
#define GPLATE_COLLECTION_H
#include <glib.h>
#include <glib-object.h>
#include <gplate/gplate-variable.h>
#include <gplate/gplate-iterator.h>
#define GPLATE_TYPE_COLLECTION (gplate_collection_get_type())
/**
* SECTION:gplate-collection
* @short_description: A collection of #GPlateVariable items.
*
* GPlateCollection is a #GInterface that defines the behavior of a
* variable collection.
*/
#define GPLATE_COLLECTION(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj), GPLATE_TYPE_COLLECTION, GPlateCollection))
#define GPLATE_IS_COLLECTION(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), GPLATE_TYPE_COLLECTION))
#define GPLATE_COLLECTION_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE((obj), GPLATE_TYPE_COLLECTION, GPlateCollectionIface))
/**
* GPlateCollection:
*
* The GPlateCollection typedef is used as a placeholder for objects
* that implement the GPlateCollection interface.
*/
typedef struct _GPlateCollection GPlateCollection;
typedef struct _GPlateCollectionIface GPlateCollectionIface;
/**
* GPlateCollectionIface:
* @gparent: The parent data.
* @find_variable: see gplate_collection_find_variable()
* @add_variable_with_name: see gplate_collection_add_variable_with_name()
* @remove_variable: see gplate_collection_remove_variable()
* @remove_all: see gplate_collection_remove_all()
* @get_iterator: see gplate_collection_get_iterator()
*
* The GPlateCollectionIface is the interface implemented by classes
* that wish to present themselves as a GPlateCollection.
*/
struct _GPlateCollectionIface {
GTypeInterface gparent;
GPlateVariable *(*find_variable)(const GPlateCollection *collection, const gchar *name);
gboolean (*add_variable_with_name)(GPlateCollection *collection, const gchar *name, GPlateVariable *variable);
gboolean (*remove_variable)(GPlateCollection *collection, GPlateVariable *variable);
gboolean (*remove_all)(GPlateCollection *collection);
GPlateIterator *(*get_iterator)(GPlateCollection *collection);
/*< private >*/
void (*_gplate_reserved1)(void);
void (*_gplate_reserved2)(void);
void (*_gplate_reserved3)(void);
void (*_gplate_reserved4)(void);
};
G_BEGIN_DECLS
/**
* gplate_collection_add:
* @collection: The GPlateCollection.
* @type: The type of the variable (<emphasis>not the
* #GType</emphasis>). This must be one of "string", "boolean",
* "integer", "float" or "double".
* @name: The name of the variable.
* @value: The value of the variable.
*
* Add a string, boolean, integer, float or double value variable to
* the @collection.
*/
#define gplate_collection_add(collection, type, name, value) { \
GPlateVariable *var = NULL; \
\
var = gplate_variable_new_from_##type((name), (value)); \
gplate_collection_add_variable(GPLATE_COLLECTION(collection), (var));\
}
/**
* gplate_collection_add_string:
* @collection: The GPlateCollection.
* @name: The name of the string variable.
* @value: The string variable's content.
*
* A helper macro for adding a string variable to a collection.
*
* This is a wrapper around the #gplate_collection_add macro.
*/
#define gplate_collection_add_string(collection, name, value) \
gplate_collection_add((collection), string, (name), (value));
/**
* gplate_collection_add_boolean:
* @collection: The GPlateCollection.
* @name: The name of the boolean variable.
* @value: The boolean variable's content.
*
* A helper macro for adding a boolean variable to a collection.
*
* This is a wrapper around the #gplate_collection_add macro.
*/
#define gplate_collection_add_boolean(collection, name, value) \
gplate_collection_add((collection), boolean, (name), (value));
/**
* gplate_collection_add_integer:
* @collection: The GPlateCollection.
* @name: The name of the integer variable.
* @value: The integer variable's content.
*
* A helper macro for adding a integer variable to a collection.
*
* This is a wrapper around the #gplate_collection_add macro.
*/
#define gplate_collection_add_integer(collection, name, value) \
gplate_collection_add((collection), integer, (name), (value));
/**
* gplate_collection_add_float:
* @collection: The GPlateCollection.
* @name: The name of the float variable.
* @value: The float variable's content.
*
* A helper macro for adding a float variable to a collection.
*
* This is a wrapper around the #gplate_collection_add macro.
*/
#define gplate_collection_add_float(collection, name, value) \
gplate_collection_add((collection), float, (name), (value));
/**
* gplate_collection_add_double:
* @collection: The GPlateCollection.
* @name: The name of the double variable.
* @value: The double variable's content.
*
* A helper macro for adding a double variable to a collection.
*
* This is a wrapper around the #gplate_collection_add macro.
*/
#define gplate_collection_add_double(collection, name, value) \
gplate_collection_add((collection), double, (name), (value));
GType gplate_collection_get_type(void);
GPlateVariable *gplate_collection_find_variable(const GPlateCollection *collection, const gchar *name);
const gchar *gplate_collection_lookup(const GPlateCollection *collection, const gchar *name);
gboolean gplate_collection_add_variable(GPlateCollection *collection, GPlateVariable *variable);
gboolean gplate_collection_add_variable_with_name(GPlateCollection *collection, const gchar *name, GPlateVariable *variable);
gboolean gplate_collection_remove_variable(GPlateCollection *collection, GPlateVariable *variable);
gboolean gplate_collection_remove_all(GPlateCollection *collection);
GPlateIterator *gplate_collection_get_iterator(GPlateCollection *collection);
G_END_DECLS
#endif /* GPLATE_COLLECTION_H */