diff -urN --exclude-from=conglomerate-r/.diffexclude conglomerate/src/cong-dispspec-registry.c conglomerate-r/src/cong-dispspec-registry.c
--- conglomerate/src/cong-dispspec-registry.c	2003-09-11 17:07:51.000000000 +0300
+++ conglomerate-r/src/cong-dispspec-registry.c	2003-10-02 00:46:25.000000000 +0300
@@ -172,10 +172,17 @@
 }
 
 /**
+ * cong_dispspec_registry_get_appropriate_dispspec
+ * @registry:
+ * @doc:
+ * @filename_extension:
+ * 
  * Routine to figure out an appropriate dispspec for use with this file.
  * Looks for a DTD; if found, it looks up the DTD in a mapping.
  * If this fails, it looks at the top-level tag and makes a guess, but asks the user for confirmation.
  * If this fails, it asks the user.
+ * 
+ * Returns:
  */
 CongDispspec*
 cong_dispspec_registry_get_appropriate_dispspec (CongDispspecRegistry* registry, 
diff -urN --exclude-from=conglomerate-r/.diffexclude conglomerate/src/cong-document.h conglomerate-r/src/cong-document.h
--- conglomerate/src/cong-document.h	2003-09-30 07:08:03.000000000 +0300
+++ conglomerate-r/src/cong-document.h	2003-10-02 01:49:02.000000000 +0300
@@ -111,12 +111,10 @@
 /**
  * cong_document_new_from_xmldoc:
  * @xmldoc:  The #xmlDocPtr which the #CongDocument is to wrap.  It takes ownership of it.
- *
  * @ds:
- *
  * @url:
  *
- * The new CongDocument is created with a reference count of 1; 
+ * The new #CongDocument is created with a reference count of 1; 
  * any views constructed of the document will increment its reference count 
  *
  * Returns: the new #CongDocument
@@ -192,7 +190,9 @@
 
 /**
  * cong_document_node_ref:
- *
+ * @doc:
+ * @node:
+ * 
  * Add an "external reference" to the node; it will not be deleted until it has been both removed from the tree
  * AND has lost all external references.
  *
@@ -203,7 +203,9 @@
 
 /**
  * cong_document_node_unref:
- *
+ * @doc:
+ * @node:
+ * 
  * Remove an "external reference" to the node; it will be deleted if it has been both removed from the tree
  * AND this was its last external reference.
  *
@@ -249,11 +251,17 @@
 CongSelection* cong_document_get_selection(CongDocument *doc);
 
 /** 
-    Every node within a document has an implied language, although the logic to determine 
-    this may depend on the dispspec, on attributes of the nodes, and perhaps even on user prefererences (and hence the value may change unexpectedly): 
-
-    FIXME: what are the ownership/ref count semantics of this function?
-*/
+ * cong_document_get_language_for_node
+ * @doc:
+ * @node:
+ * 
+ * Every node within a document has an implied language, although the logic to determine 
+ * this may depend on the dispspec, on attributes of the nodes, and perhaps even on user prefererences (and hence the value may change unexpectedly).
+ * 
+ * FIXME: what are the ownership/ref count semantics of this function?
+ * 
+ * Returns:
+ */
 PangoLanguage*
 cong_document_get_language_for_node(CongDocument *doc, 
 				    CongNodePtr node);
@@ -379,10 +387,16 @@
 			   int c);
 
 /**
+ * cong_document_get_dtd_element
+ * @cong_doc:
+ * @node:
+ * 
  * Helper function to get the xmlElementPtr within the DTD for a node
  * Currently only looks at the actual DTD, but in future might attempt
  * to use the dispspec to infer an DTD and return that
  * So don't store the return value; it might get deleted etc
+ * 
+ * Returns:
  */
 xmlElementPtr
 cong_document_get_dtd_element (CongDocument *cong_doc, 
diff -urN --exclude-from=conglomerate-r/.diffexclude conglomerate/src/cong-dtd.h conglomerate-r/src/cong-dtd.h
--- conglomerate/src/cong-dtd.h	2003-09-06 23:03:02.000000000 +0300
+++ conglomerate-r/src/cong-dtd.h	2003-09-30 15:42:37.000000000 +0300
@@ -48,8 +48,13 @@
 			     gpointer user_data);
 
 /**
+ * cong_dtd_element_guess_dispspec_type
+ * @element:
+ * 
  * Given a DTD element, make a guess as to an appropriate xds element type.
  * Useful when autogenerating CongDispspec from DTD files
+ * 
+ * Returns: 
  */
 enum CongElementType
 cong_dtd_element_guess_dispspec_type (xmlElementPtr element);
diff -urN --exclude-from=conglomerate-r/.diffexclude conglomerate/src/cong-editor-node.h conglomerate-r/src/cong-editor-node.h
--- conglomerate/src/cong-editor-node.h	2003-08-09 20:36:47.000000000 +0300
+++ conglomerate-r/src/cong-editor-node.h	2003-09-30 15:52:18.000000000 +0300
@@ -40,6 +40,8 @@
 
 
 /**
+ * CongEditorNode
+ * 
  * A CongEditorNode is a per-editor-widget GObject, and represents a node that is visited in a traversal of the xml tree.
  * Hence there is generally a 1-1 mapping between xml nodes and CongEditorNodes.  When an xmlnode is added or removed from the tree, 
  * even temporarily, then a corresponding CongEditorNode is added/removed.
@@ -138,10 +140,15 @@
 cong_editor_node_get_flow_type (CongEditorNode *editor_node);
 
 /**
+ * cong_editor_node_is_referenced_entity_decl
+ * @editor_node:
+ *
  *  Entity decls can be visited in the tree both below the DTD node, and below each entity ref node that references them.
  *  This function returns TRUE iff the editor_node represents the latter case.
  *  This is useful e.g. if you want to know the "effective siblings" of the node, which should be the other entity decls in the
  *  former case, and should be NULL in the latter case.
+ *
+ * Returns:
  */
 gboolean
 cong_editor_node_is_referenced_entity_decl (CongEditorNode *editor_node);
diff -urN --exclude-from=conglomerate-r/.diffexclude conglomerate/src/cong-eel.c conglomerate-r/src/cong-eel.c
--- conglomerate/src/cong-eel.c	2003-09-11 18:19:53.000000000 +0300
+++ conglomerate-r/src/cong-eel.c	2003-10-02 01:59:45.000000000 +0300
@@ -101,10 +101,11 @@
 /**
  * cong_eel_gdk_color_to_rgb
  * @color: A GdkColor style color.
- * Returns: An rgb value.
  *
  * Converts from a GdkColor stlye color to a gdk_rgb one.
  * Alpha gets set to fully opaque
+ * 
+ * Returns: An rgb value.
  */
 guint32
 cong_eel_gdk_color_to_rgb (const GdkColor *color)
@@ -174,11 +175,16 @@
 }
 
 /**
+ * split_xmlname:
+ * @xml_name:
+ * 
  * Splits things like "this-is-a-tag" into its individual words.
  * Can handle hyphenated words.
  * FIXME:  Add support for splitting caps-seperated things like "ThisIsATag"
  * FIXME:  Probably should convert everything to lower case as well on output
  * FIXME:  To be really smart, we could try to spot acronyms and fully capitalise them...  would require a dictionary though.
+ * 
+ * Returns:
  */
 static gchar** split_xmlname(const gchar *xml_name)
 {
diff -urN --exclude-from=conglomerate-r/.diffexclude conglomerate/src/cong-error-dialog.h conglomerate-r/src/cong-error-dialog.h
--- conglomerate/src/cong-error-dialog.h	2003-05-25 12:59:33.000000000 +0300
+++ conglomerate-r/src/cong-error-dialog.h	2003-09-30 15:57:31.000000000 +0300
@@ -107,8 +107,17 @@
 								   const gchar *command_line);
 
 /**
+ * cong_error_dialog_new_from_shell_command_failure_with_argv
+ * @parent_window:
+ * @what_failed:
+ * @exit_status:
+ * @standard_error:
+ * @argv
+ * 
  * Routine to manufacture an error dialog for when some shell operation fails, when you have access to the stderr output in the form of a string.
  * argv is a NULL terminated array of strings.
+ * 
+ * Returns: 
  */
 GtkDialog*
 cong_error_dialog_new_from_shell_command_failure_with_argv(GtkWindow *parent_window,
@@ -175,9 +184,17 @@
 					     const GnomeVFSFileSize* file_size);
 
 /**
+ * cong_error_dialog_new_from_file_operation_failure
+ * @parent_window:
+ * @what_failed:
+ * @file_uri: the URI from which you tried to access file.
+ * @vfs_result:
+ * @technical_details:
+ * 
  * Routine to manufacture an error dialog for when some file operation fails that doesn't fall into one of the categories above.
  * Displays what operation has failed, with a convenience button to get more techical information.
- * @vfs_uri:  the URI from which you tried to access file.
+ * 
+ * Returns:
  */
 GtkDialog*
 cong_error_dialog_new_from_file_operation_failure(GtkWindow *parent_window,
diff -urN --exclude-from=conglomerate-r/.diffexclude conglomerate/src/cong-location.h conglomerate-r/src/cong-location.h
--- conglomerate/src/cong-location.h	2003-08-13 20:09:56.000000000 +0300
+++ conglomerate-r/src/cong-location.h	2003-09-30 15:58:12.000000000 +0300
@@ -26,8 +26,10 @@
 #define __CONG_LOCATION_H__
 
 /**
-   Struct representing a location within a document, with both a node ptr and a byte offset into the text.
-   The text is stored as UTF-8, and the offset is a byte offset, not a character offset.
+ * CongLocation
+ * 
+ * Struct representing a location within a document, with both a node ptr and a byte offset into the text.
+ * The text is stored as UTF-8, and the offset is a byte offset, not a character offset.
  */
 typedef struct _CongLocation
 {
diff -urN --exclude-from=conglomerate-r/.diffexclude conglomerate/src/cong-plugin.h conglomerate-r/src/cong-plugin.h
--- conglomerate/src/cong-plugin.h	2003-09-23 00:03:59.000000000 +0300
+++ conglomerate-r/src/cong-plugin.h	2003-09-30 17:21:02.000000000 +0300
@@ -223,10 +223,16 @@
 gchar* cong_plugin_get_gconf_namespace(CongPlugin *plugin);
 
 /**
-   Convert a "local" GConf key for this plugin to a GConf key with a full-path.
-   e.g. converts "enable-fubar" to "/apps/conglomerate/plugins/docbook/enable-fubar"
-   
-   Caller must delete returned string.
+ * cong_plugin_get_gconf_key
+ * @plugin:
+ * @local_part:
+ * 
+ * Convert a "local" GConf key for this plugin to a GConf key with a full-path.
+ * e.g. converts "enable-fubar" to "/apps/conglomerate/plugins/docbook/enable-fubar"
+ *  
+ * Caller must delete returned string.
+ * 
+ * Returns:
  */
 gchar* cong_plugin_get_gconf_key(CongPlugin *plugin, const gchar *local_part);
 
@@ -237,10 +243,16 @@
 gchar* cong_functionality_get_gconf_namespace(CongFunctionality* functionality);
 
 /**
-   Convert a "local" GConf key for this plugin to a GConf key with a full-path.
-   e.g. converts "enable-fubar" to "/apps/conglomerate/plugins/docbook/enable-fubar"
-   
-   Caller must delete returned string.
+ * cong_plugin_functionality_get_gconf_key
+ * @functionality:
+ * @local_part:
+ * 
+ * Convert a "local" GConf key for this plugin to a GConf key with a full-path.
+ * e.g. converts "enable-fubar" to "/apps/conglomerate/plugins/docbook/enable-fubar"
+ *   
+ * Caller must delete returned string.
+ * 
+ * Returns:
  */
 gchar* cong_functionality_get_gconf_key(CongFunctionality *functionality, const gchar *local_part);
 
diff -urN --exclude-from=conglomerate-r/.diffexclude conglomerate/src/cong-text-cache.h conglomerate-r/src/cong-text-cache.h
--- conglomerate/src/cong-text-cache.h	2003-08-04 14:39:51.000000000 +0300
+++ conglomerate-r/src/cong-text-cache.h	2003-09-30 17:22:21.000000000 +0300
@@ -31,6 +31,8 @@
 
 #if 0
 /**
+ * CongTextCacheSpan
+ * 
  * Struct representing a run of characters within a plaintext cache from a specific text node; 
  * useful for converting from PangoLayoutLines back to the underlying XML: 
  * There can be more than one of these for a particular text node; each is a subset of the characters
diff -urN --exclude-from=conglomerate-r/.diffexclude conglomerate/src/cong-util.c conglomerate-r/src/cong-util.c
--- conglomerate/src/cong-util.c	2003-09-12 01:35:43.000000000 +0300
+++ conglomerate-r/src/cong-util.c	2003-09-30 23:27:49.000000000 +0300
@@ -566,3 +566,119 @@
 
 	gdk_gc_unref(gc);
 }
+
+/*
+  A routine that tries to load all the bytes requested from the handle into the buffer and bails out on any failure
+ */
+GnomeVFSResult
+cong_vfs_read_bytes(GnomeVFSHandle* vfs_handle, char* buffer, GnomeVFSFileSize bytes)
+{
+	GnomeVFSFileSize bytes_read;
+	GnomeVFSResult vfs_result = gnome_vfs_read(vfs_handle,buffer,bytes,&bytes_read);
+
+	g_assert(bytes==bytes_read); /* for now */
+
+	return vfs_result;
+}
+
+/* 
+   A routine that tries to syncronously load a file into a buffer in memory (surely this exists already somewhere?)
+*/
+GnomeVFSResult
+cong_vfs_new_buffer_from_file(const char* filename, char** buffer, GnomeVFSFileSize* size)
+{
+	GnomeVFSResult vfs_result;
+	GnomeVFSURI* uri;
+
+	g_return_val_if_fail(filename,GNOME_VFS_ERROR_BAD_PARAMETERS);
+	g_return_val_if_fail(buffer,GNOME_VFS_ERROR_BAD_PARAMETERS);
+	g_return_val_if_fail(size,GNOME_VFS_ERROR_BAD_PARAMETERS);
+
+	/* it seems that GnomeVFS works with absolute paths, so
+	   if the filename is not absolute, build it */
+	if (!g_path_is_absolute (filename)){
+		gchar *absolute_path = g_strconcat (g_get_current_dir(), GNOME_VFS_URI_PATH_STR, filename, NULL);
+
+		uri = gnome_vfs_uri_new (absolute_path);
+
+		g_free (absolute_path);
+
+	} else {
+
+		uri = gnome_vfs_uri_new (filename);
+	}
+
+	vfs_result = cong_vfs_new_buffer_from_uri(uri, buffer, size);
+
+	gnome_vfs_uri_unref(uri);
+
+	return vfs_result;
+}
+
+GnomeVFSResult
+cong_vfs_new_buffer_from_uri(GnomeVFSURI* uri, char** buffer, GnomeVFSFileSize* size)
+{
+	GnomeVFSResult vfs_result;
+	GnomeVFSHandle *vfs_handle;
+
+	g_return_val_if_fail(uri,GNOME_VFS_ERROR_BAD_PARAMETERS);
+	g_return_val_if_fail(buffer,GNOME_VFS_ERROR_BAD_PARAMETERS);
+	g_return_val_if_fail(size,GNOME_VFS_ERROR_BAD_PARAMETERS);
+
+	vfs_result = gnome_vfs_open_uri(&vfs_handle,
+					uri,
+					GNOME_VFS_OPEN_READ);
+
+	if (GNOME_VFS_OK!=vfs_result) {
+		return vfs_result;
+	} else {
+		GnomeVFSFileInfo *info;
+		*buffer=NULL;
+		
+		info = gnome_vfs_file_info_new ();
+
+		/* Get the size of the file: */
+		vfs_result = gnome_vfs_get_file_info_from_handle(vfs_handle,
+								 info,
+								 GNOME_VFS_FILE_INFO_DEFAULT);
+		if (GNOME_VFS_OK!=vfs_result) {
+			gnome_vfs_close(vfs_handle);
+			gnome_vfs_file_info_unref (info);
+			
+			return vfs_result;
+		}
+
+		if (!(info->valid_fields & GNOME_VFS_FILE_INFO_FIELDS_SIZE)) {
+			gnome_vfs_close(vfs_handle);
+			gnome_vfs_file_info_unref (info);
+			
+			return GNOME_VFS_ERROR_IO; /* FIXME: is this appropriate? */
+		}
+
+		
+		/* Allocate the buffer: */
+		*buffer = g_malloc(info->size);
+		
+		/* Read the file into the buffer: */
+		vfs_result = cong_vfs_read_bytes(vfs_handle, *buffer, info->size);
+		
+		if (GNOME_VFS_OK!=vfs_result) {
+			
+			g_free(*buffer);
+			gnome_vfs_close(vfs_handle);
+			gnome_vfs_file_info_unref (info);
+
+			*buffer=NULL;
+			
+			return vfs_result;
+		}
+		
+		gnome_vfs_close(vfs_handle);
+		
+		*size = info->size;
+		
+		gnome_vfs_file_info_unref (info);
+
+		return GNOME_VFS_OK;
+	}
+}
diff -urN --exclude-from=conglomerate-r/.diffexclude conglomerate/src/cong-util.h conglomerate-r/src/cong-util.h
--- conglomerate/src/cong-util.h	2003-09-29 05:06:21.000000000 +0300
+++ conglomerate-r/src/cong-util.h	2003-09-30 23:43:07.000000000 +0300
@@ -27,6 +27,15 @@
 
 G_BEGIN_DECLS
 
+/* moved from main.c */
+GnomeVFSResult
+cong_vfs_new_buffer_from_file(const char* filename, char** buffer, GnomeVFSFileSize* size);
+
+/* moved from main.c */
+GnomeVFSResult
+cong_vfs_new_buffer_from_uri(GnomeVFSURI* uri, char** buffer, GnomeVFSFileSize* size);
+
+
 /* Handy utility functions: */
 
 gboolean 
@@ -37,7 +46,6 @@
 
 /**
  * cong_util_cleanup_text:
- *
  * @text:  input xml text
  *
  * Handy function for taking xml text and turning it into something you can see in a log: tabs and carriage returns etc are turned into visible characters.
@@ -67,6 +75,8 @@
 gchar*
 cong_utils_get_norman_walsh_stylesheet (const gchar *stylesheet_relative_path);
 
+
+
 /**
    Icon loading; take an icon basename e.g. "cong-docbook-set", convert to a filename and load it.
  */
diff -urN --exclude-from=conglomerate-r/.diffexclude conglomerate/src/global.h conglomerate-r/src/global.h
--- conglomerate/src/global.h	2003-09-30 07:08:06.000000000 +0300
+++ conglomerate-r/src/global.h	2003-09-30 19:00:57.000000000 +0300
@@ -170,14 +170,28 @@
 			   const gchar *filename_extension);
 
 /**
+ * cong_vfs_new_buffer_from_file
+ * @filename:
+ * @buffer:
+ * @size:
+ * 
  * A routine that tries to syncronously load a file into a buffer in memory (surely this exists already somewhere?)
  * (I believe that CVS gnome-vfs has a routine gnome_vfs_read_entire_file that does this)
-*/
+ * 
+ * Returns:
+ */
 GnomeVFSResult
 cong_vfs_new_buffer_from_file(const char* filename, char** buffer, GnomeVFSFileSize* size);
 
 /**
+ * cong_vfs_new_buffer_from_uri
+ * @uri:
+ * @buffer:
+ * @size:
+ * 
  * A routine that tries to syncronously load a file into a buffer in memory (surely this exists already somewhere?)
+ * 
+ * Returns:
 */
 GnomeVFSResult
 cong_vfs_new_buffer_from_uri(GnomeVFSURI* uri, char** buffer, GnomeVFSFileSize* size);
diff -urN --exclude-from=conglomerate-r/.diffexclude conglomerate/src/main.c conglomerate-r/src/main.c
--- conglomerate/src/main.c	2003-09-23 00:03:59.000000000 +0300
+++ conglomerate-r/src/main.c	2003-09-30 23:30:18.000000000 +0300
@@ -14,6 +14,7 @@
 #include "cong-app.h"
 #include "cong-fake-plugin-hooks.h"
 #include "cong-primary-window.h"
+#include "cong-util.h"
 
 #define TEST_BIG_FONTS 0
 
@@ -21,124 +22,6 @@
 #define AUTOGENERATE_DS
 */
 
-/*
-  A routine that tries to load all the bytes requested from the handle into the buffer and bails out on any failure
- */
-GnomeVFSResult
-cong_vfs_read_bytes(GnomeVFSHandle* vfs_handle, char* buffer, GnomeVFSFileSize bytes)
-{
-	GnomeVFSFileSize bytes_read;
-	GnomeVFSResult vfs_result = gnome_vfs_read(vfs_handle,buffer,bytes,&bytes_read);
-
-	g_assert(bytes==bytes_read); /* for now */
-
-	return vfs_result;
-}
-
-/* 
-   A routine that tries to syncronously load a file into a buffer in memory (surely this exists already somewhere?)
-*/
-GnomeVFSResult
-cong_vfs_new_buffer_from_file(const char* filename, char** buffer, GnomeVFSFileSize* size)
-{
-	GnomeVFSResult vfs_result;
-	GnomeVFSURI* uri;
-
-	g_return_val_if_fail(filename,GNOME_VFS_ERROR_BAD_PARAMETERS);
-	g_return_val_if_fail(buffer,GNOME_VFS_ERROR_BAD_PARAMETERS);
-	g_return_val_if_fail(size,GNOME_VFS_ERROR_BAD_PARAMETERS);
-
-	/* it seems that GnomeVFS works with absolute paths, so
-	   if the filename is not absolute, build it */
-	if (!g_path_is_absolute (filename)){
-		gchar *absolute_path = g_strconcat (g_get_current_dir(), GNOME_VFS_URI_PATH_STR, filename, NULL);
-
-		uri = gnome_vfs_uri_new (absolute_path);
-
-		g_free (absolute_path);
-
-	} else {
-
-		uri = gnome_vfs_uri_new (filename);
-	}
-
-	vfs_result = cong_vfs_new_buffer_from_uri(uri, buffer, size);
-
-	gnome_vfs_uri_unref(uri);
-
-	return vfs_result;
-}
-
-GnomeVFSResult
-cong_vfs_new_buffer_from_uri(GnomeVFSURI* uri, char** buffer, GnomeVFSFileSize* size)
-{
-	GnomeVFSResult vfs_result;
-	GnomeVFSHandle *vfs_handle;
-
-	g_return_val_if_fail(uri,GNOME_VFS_ERROR_BAD_PARAMETERS);
-	g_return_val_if_fail(buffer,GNOME_VFS_ERROR_BAD_PARAMETERS);
-	g_return_val_if_fail(size,GNOME_VFS_ERROR_BAD_PARAMETERS);
-
-	vfs_result = gnome_vfs_open_uri(&vfs_handle,
-					uri,
-					GNOME_VFS_OPEN_READ);
-
-	if (GNOME_VFS_OK!=vfs_result) {
-		return vfs_result;
-	} else {
-		GnomeVFSFileInfo *info;
-		*buffer=NULL;
-		
-		info = gnome_vfs_file_info_new ();
-
-		/* Get the size of the file: */
-		vfs_result = gnome_vfs_get_file_info_from_handle(vfs_handle,
-								 info,
-								 GNOME_VFS_FILE_INFO_DEFAULT);
-		if (GNOME_VFS_OK!=vfs_result) {
-			gnome_vfs_close(vfs_handle);
-			gnome_vfs_file_info_unref (info);
-			
-			return vfs_result;
-		}
-
-		if (!(info->valid_fields & GNOME_VFS_FILE_INFO_FIELDS_SIZE)) {
-			gnome_vfs_close(vfs_handle);
-			gnome_vfs_file_info_unref (info);
-			
-			return GNOME_VFS_ERROR_IO; /* FIXME: is this appropriate? */
-		}
-
-		
-		/* Allocate the buffer: */
-		*buffer = g_malloc(info->size);
-		
-		/* Read the file into the buffer: */
-		vfs_result = cong_vfs_read_bytes(vfs_handle, *buffer, info->size);
-		
-		if (GNOME_VFS_OK!=vfs_result) {
-			
-			g_free(*buffer);
-			gnome_vfs_close(vfs_handle);
-			gnome_vfs_file_info_unref (info);
-
-			*buffer=NULL;
-			
-			return vfs_result;
-		}
-		
-		gnome_vfs_close(vfs_handle);
-		
-		*size = info->size;
-		
-		gnome_vfs_file_info_unref (info);
-
-		return GNOME_VFS_OK;
-	}
-}
-
-
-
 void insert_element_init()
 {
 	GdkColor gcol;
diff -urN --exclude-from=conglomerate-r/.diffexclude conglomerate/src/popup.c conglomerate-r/src/popup.c
--- conglomerate/src/popup.c	2003-09-30 07:08:07.000000000 +0300
+++ conglomerate-r/src/popup.c	2003-09-30 17:24:24.000000000 +0300
@@ -1052,10 +1052,17 @@
 
 
 /**
+ * string_selection_dialog
+ * @title:
+ * @element_description:
+ * @elements:
+ * 
  * Popup a modal, blocking dialog to obtain
  * the user's choice between a list of char *.
  * Returns a new char * of the element name 
  * selected, which must be freed by caller.
+ * 
+ * Returns:
  */
 gchar *string_selection_dialog(gchar *title, gchar *element_description, GList *elements) 
 {
diff -urN --exclude-from=conglomerate-r/.diffexclude conglomerate/src/xmldata.c conglomerate-r/src/xmldata.c
--- conglomerate/src/xmldata.c	2003-09-30 07:08:07.000000000 +0300
+++ conglomerate-r/src/xmldata.c	2003-09-30 18:09:20.000000000 +0300
@@ -161,6 +161,10 @@
 }
 
 /**
+ * xml_add+required_children
+ * @doc:
+ * @node:
+ *
  * In the presence of a DTD, adds all children required
  * by the DTD to the node.  This is a recursive process,
  * and as such will add subchildren if necessary.
@@ -175,7 +179,7 @@
  * If no DTD is present, this function will default to
  * simply adding a text node under the node as well.
  *
- * Returns a boolean telling whether the structure of the
+ * Returns: a boolean telling whether the structure of the
  * node passed is now valid under a DTD.  If no DTD exists,
  * this will return FALSE.
  */
@@ -206,10 +210,14 @@
 }
 		
 /**
+ * xml_add_required_sub_elements
+ * @cong_doc:
+ * node:
+ * 
  * Helper function to add the required children
  * to a node.
  *
- * Returns whether the node is now valid
+ * Returns: whether the node is now valid
  */
 static gboolean xml_add_required_sub_elements(CongDocument *cong_doc, CongNodePtr node) {
 	xmlDocPtr doc;
@@ -309,10 +317,15 @@
 }
 
 /**
+ * xml_add_required_content
+ * @cong_doc:
+ * @content:
+ * @node:
+ * 
  * Adds required children from an
  * input content model.
  *
- * Returns whether all required content was added
+ * Returns: whether all required content was added
  */
 static gboolean xml_add_required_content(CongDocument *cong_doc, xmlElementContentPtr content, xmlNodePtr node) {
 	xmlNodePtr new_node;
@@ -366,11 +379,16 @@
 }
 
 /**
+ * xml_add_required_content_choice
+ * @cong_doc:
+ * @content:
+ * @node:
+ * 
  * Allows the user to select between a set
  * of choices for a required content element.
  * Adds that choice to the node.
  *
- * Returns whether the choice was correctly selected and added
+ * Returns: whether the choice was correctly selected and added
  */
 static gboolean xml_add_required_content_choice(CongDocument *cong_doc, xmlElementContentPtr content, xmlNodePtr node) {
 	GString *description;
@@ -424,11 +442,16 @@
 	
  
 /**
+ * xml_add_optional_text_nodes
+ * @cong_doc:
+ * @content:
+ * node:
+ * 
  * Adds an optional text node when it
  * conforms to the content model, such that
  * the user may type.
  *
- * @return whether a text node has been added
+ * Returns: whether a text node has been added
  */
 static gboolean xml_add_optional_text_nodes(CongDocument *cong_doc, xmlElementContentPtr content, xmlNodePtr node) {
 	xmlNodePtr new_node;
@@ -457,10 +480,18 @@
 /**** end of the add_required stuff ****/
 
 /**
+ * xml_valid_get_potential_element_children
+ * @ctree:
+ * @list:
+ * @len:
+ * @max:
+ * 
  * Reimplementation of xmlValidGetPotentialChildren that *only*
  * returns children of element type, not of PCDATA type.
  *
  * Otherwise, behaves the same as xmlValidGetPotentialChildren.
+ * 
+ * Returns:
  */
 static gint 
 xml_valid_get_potential_element_children(xmlElementContent *ctree, 
@@ -498,12 +529,21 @@
 }
 
 /**
+ * wrap_xml_valid_get_valid_elements
+ * @doc:
+ * @parent:
+ * @next_sibling:
+ * @elements:
+ * @max:
+ * 
  * Wrapper function for libxml's xmlValidGetValidElements that
  * handles the corner case of when the parent has no children.
  * xmlValidGetValidElements parameter structure cannot handle this case.
  *
  * Otherwise, behaves the same as xmlValidGetValidElements.
  * Being rewritten: now uses CongDocument, so may be able to get at DTD information even if none attached...
+ * 
+ * Returns:
  */
 static gint 
 wrap_xml_valid_get_valid_elements (CongDocument *doc, 
@@ -579,6 +619,11 @@
 #define MAX_ELEMENTS 256
 
 /**
+ * cong_document_get_valid_new_child_elements
+ * @doc:
+ * @node: node for which to get valid children
+ * @tag_type: either CONG_ELEMENT_TYPE_STRUCTURAL, CONG_ELEMENT_TYPE_SPAN, or CONG_ELEMENT_TYPE_ALL
+ * 
  * Get the set of valid children for a node.  If the document
  * contains a DTD, this function will return the intersection
  * of the valid children and elements in the display spec of 
@@ -586,9 +631,7 @@
  * If the document does not contain a dtd, the function will fallback
  * on returning the elements in the display spec of type tag_type.
  *
- * @param node CongNodePtr node for which to get valid children
- * @param tag_type either CONG_ELEMENT_TYPE_STRUCTURAL, CONG_ELEMENT_TYPE_SPAN, or CONG_ELEMENT_TYPE_ALL
- * @return GList of CongDispspecElement
+ * Returns: GList of CongDispspecElement
  */
 GList*
 cong_document_get_valid_new_child_elements (CongDocument *doc,
@@ -615,6 +658,11 @@
 
 
 /**
+ * cong_document_get_valid_new_previous_sibling_elements
+ * @doc:
+ * @node: CongNodePtr node for which to get valid previous siblings
+ * @tag_type: either CONG_ELEMENT_TYPE_STRUCTURAL, CONG_ELEMENT_TYPE_SPAN, or CONG_ELEMENT_TYPE_ALL
+ * 
  * Get the set of valid previous siblings for a node.  If the document
  * contains a DTD, this function will return the intersection
  * of the valid previous siblings and elements in the display spec of 
@@ -622,9 +670,7 @@
  * If the document does not contain a dtd, the function will fallback
  * on returning the elements in the display spec of type tag_type.
  *
- * @param node CongNodePtr node for which to get valid previous siblings
- * @param tag_type either CONG_ELEMENT_TYPE_STRUCTURAL, CONG_ELEMENT_TYPE_SPAN, or CONG_ELEMENT_TYPE_ALL
- * @return GList of CongDispspecElement
+ * Returns: GList of CongDispspecElement
  */
 GList* 
 cong_document_get_valid_new_previous_sibling_elements (CongDocument *doc,
@@ -646,6 +692,11 @@
 }
 
 /**
+ * cong_document_get_valid_new_next_sibling_elements
+ * @doc:
+ * @node: node for which to get valid next siblings
+ * @tag_type: either CONG_ELEMENT_TYPE_STRUCTURAL, CONG_ELEMENT_TYPE_SPAN, or CONG_ELEMENT_TYPE_ALL
+ * 
  * Get the set of valid next siblings for a node.  If the document
  * contains a DTD, this function will return the intersection
  * of the valid next siblings and elements in the display spec of 
@@ -653,10 +704,7 @@
  * If the document does not contain a dtd, the function will fallback
  * on returning the elements in the display spec of type tag_type.
  *
- * @param ds CongDispsec* display spec
- * @param node CongNodePtr node for which to get valid next siblings
- * @param tag_type either CONG_ELEMENT_TYPE_STRUCTURAL, CONG_ELEMENT_TYPE_SPAN, or CONG_ELEMENT_TYPE_ALL
- * @return GList of CongDispspecElement
+ * Returns: GList of CongDispspecElement
  */
 GList* 
 cong_document_get_valid_new_next_sibling_elements (CongDocument* doc, 
@@ -702,9 +750,17 @@
 }
 
 /**
+ * xml_filter_valid_children_with_dispspec
+ * @ds:
+ * @elements:
+ * @elements_length:
+ * @tag_type:
+ * 
  * Find the intersection of a list of valid children
  * and a displayspec, returning a list of the displayspec elements
  * that are in the intersection.
+ * 
+ * Returns:
  */
 static GList *xml_filter_valid_children_with_dispspec(CongDispspec* ds, const xmlChar **elements, gint elements_length, enum CongElementType tag_type) {
 	CongDispspecElement *element;
@@ -735,8 +791,14 @@
 }
 
 /**
+ * xml_get_elements_from_dispspec
+ * @ds:
+ * @tag_type:
+ * 
  * Get all elements from the display spec that
  * are of tag_type.
+ * 
+ * Returns:
  */
 static GList* xml_get_elements_from_dispspec(CongDispspec* ds, enum CongElementType tag_type) {
 	CongDispspecElement *element;
