Add some documentation comments, fix some missing statics

6 files changed, 166 insertions, 15 deletions

diff --git a/gtk/gtkfilechooserdefault.c b/gtk/gtkfilechooserdefault.c
index b4eb21a798..b19ee1adc1 100644
--- a/gtk/gtkfilechooserdefault.c
+++ b/gtk/gtkfilechooserdefault.c
@@ -515,7 +515,7 @@ list_selection_changed (GtkTreeSelection          *selection,
   g_signal_emit_by_name (impl, "selection_changed", 0);
 }
 
-void
+static void
 name_data_func (GtkTreeViewColumn *tree_column,
 		GtkCellRenderer   *cell,
 		GtkTreeModel      *tree_model,
diff --git a/gtk/gtkfilechooserutils.c b/gtk/gtkfilechooserutils.c
index 4a88ddcc03..31808d64b8 100644
--- a/gtk/gtkfilechooserutils.c
+++ b/gtk/gtkfilechooserutils.c
@@ -39,6 +39,17 @@ static void    delegate_current_folder_changed (GtkFileChooser *chooser,
 static void    delegate_selection_changed      (GtkFileChooser *chooser,
 						gpointer        data);
 
+/**
+ * _gtk_file_chooser_install_properties:
+ * @klass: the class structure for a type deriving from #GObject
+ * 
+ * Installs the necessary properties for a class implementing
+ * #GtkFileChooser. A #GtkParamSpecOverride property is installed
+ * for each property, using the values from the #GtkFileChooserProp
+ * enumeration. The caller must make sure itself that the enumeration
+ * values don't collide with some other property values they
+ * are using.
+ **/
 void
 _gtk_file_chooser_install_properties (GObjectClass *klass)
 {
@@ -79,6 +90,17 @@ _gtk_file_chooser_install_properties (GObjectClass *klass)
 							  G_PARAM_READWRITE));
 }
 
+/**
+ * _gtk_file_chooser_delegate_iface_init:
+ * @iface: a #GtkFileChoserIface structure
+ * 
+ * An interface-initialization function for use in cases where
+ * an object is simply delegating the methods, signals of
+ * the #GtkFileChooser interface to another object.
+ * _gtk_file_chooser_set_delegate() must be called on each
+ * instance of the object so that the delegate object can
+ * be found.
+ **/
 void
 _gtk_file_chooser_delegate_iface_init (GtkFileChooserIface *iface)
 {
@@ -91,6 +113,17 @@ _gtk_file_chooser_delegate_iface_init (GtkFileChooserIface *iface)
   iface->get_uris = delegate_get_uris;
 }
 
+/**
+ * _gtk_file_chooser_set_delegate:
+ * @receiver: a GOobject implementing #GtkFileChooser
+ * @delegate: another GObject implementing #GtkFileChooser
+ *
+ * Establishes that calls on @receiver for #GtkFileChooser
+ * methods should be delegated to @delegate, and that
+ * #GtkFileChooser signals emitted on @delegate should be
+ * forwarded to @receiver. Must be used in confunction with
+ * _gtk_file_chooser_delegate_iface_init().
+ **/
 void
 _gtk_file_chooser_set_delegate (GtkFileChooser *receiver,
 				GtkFileChooser *delegate)
@@ -106,7 +139,7 @@ _gtk_file_chooser_set_delegate (GtkFileChooser *receiver,
 		    G_CALLBACK (delegate_selection_changed), receiver);
 }
 
-GtkFileChooser *
+static GtkFileChooser *
 get_delegate (GtkFileChooser *receiver)
 {
   return g_object_get_data (G_OBJECT (receiver), "gtk-file-chooser-delegate");
diff --git a/gtk/gtkfilechooserwidget.c b/gtk/gtkfilechooserwidget.c
index 3a168bbbe5..941a2d1592 100644
--- a/gtk/gtkfilechooserwidget.c
+++ b/gtk/gtkfilechooserwidget.c
@@ -105,7 +105,7 @@ gtk_file_chooser_widget_init (GtkFileChooserWidget *chooser_widget)
   
   gtk_widget_push_composite_child ();
 
-  priv->impl = _gtk_file_chooser_impl_default_new (g_object_new (GTK_TYPE_FILE_SYSTEM_UNIX, NULL));
+  priv->impl = _gtk_file_chooser_impl_default_new (_gtk_file_system_unix_new ());
   gtk_box_pack_start (GTK_BOX (chooser_widget), priv->impl, TRUE, TRUE, 0);
   gtk_widget_show (priv->impl);
 
diff --git a/gtk/gtkfilesystemmodel.c b/gtk/gtkfilesystemmodel.c
index 067ff58f1e..b7a29fe1e3 100644
--- a/gtk/gtkfilesystemmodel.c
+++ b/gtk/gtkfilesystemmodel.c
@@ -126,15 +126,14 @@ static void           file_model_node_ref        (FileModelNode      *node);
 static void           file_model_node_unref      (GtkFileSystemModel *model,
 						  FileModelNode      *node);
 
-const GtkFileInfo *   file_model_node_get_info   (GtkFileSystemModel *model,
-						  FileModelNode      *node);
-static gboolean       file_model_node_is_visible (GtkFileSystemModel *model,
-						  FileModelNode      *node);
-static void           file_model_node_clear      (GtkFileSystemModel *model,
-						  FileModelNode      *node);
-
-static FileModelNode *file_model_node_get_children (GtkFileSystemModel *model,
-						    FileModelNode      *node);
+static const GtkFileInfo *file_model_node_get_info     (GtkFileSystemModel *model,
+							FileModelNode      *node);
+static gboolean           file_model_node_is_visible   (GtkFileSystemModel *model,
+							FileModelNode      *node);
+static void               file_model_node_clear        (GtkFileSystemModel *model,
+							FileModelNode      *node);
+static FileModelNode *    file_model_node_get_children (GtkFileSystemModel *model,
+							FileModelNode      *node);
 
 GType
 _gtk_file_system_model_get_type (void)
@@ -505,6 +504,30 @@ gtk_file_system_model_unref_node (GtkTreeModel *tree_model,
 			 iter->user_data);
 }
 
+/**
+ * _gtk_file_system_model_new:
+ * @file_system: an object implementing #GtkFileSystem
+ * @root_uri: the URI of root of the file system to display,
+ *            or %NULL to display starting from the
+ *            root or roots of the fielsystem.
+ * @max_depth: the maximum depth from the children of @root_uri
+ *             or the roots of the file system to display in
+ *             the file selector). A depth of 0 displays
+ *             only the immediate children of @root_uri,
+ *             or the roots of the filesystem. -1 for no
+ *             maximum depth.
+ * @types: a bitmask indicating the types of information
+ *         that is desired about the files. This will
+ *         determine what information is returned by
+ *         _gtk_file_system_model_get_info().
+ *
+ * Creates a new #GtkFileSystemModel object. The #GtkFileSystemModel
+ * object wraps a #GtkFileSystem interface as a #GtkTreeModel.
+ * Using the @root_uri and @max_depth parameters, the tree model
+ * can be restricted to a subportion of the entire file system.
+ * 
+ * Return value: the newly created #GtkFileSystemModel object.
+ **/
 GtkFileSystemModel *
 _gtk_file_system_model_new (GtkFileSystem  *file_system,
 			    const gchar    *root_uri,
@@ -625,6 +648,14 @@ model_refilter_recurse (GtkFileSystemModel *model,
     }
 }
 
+/**
+ * _gtk_file_system_model_set_show_hidden:
+ * @model: a #GtkFileSystemModel
+ * @show_hidden: whether hidden files should be displayed
+ * 
+ * Sets whether hidden files should be included in the #GtkTreeModel
+ * for display.
+ **/
 void
 _gtk_file_system_model_set_show_hidden (GtkFileSystemModel *model,
 					gboolean            show_hidden)
@@ -643,6 +674,14 @@ _gtk_file_system_model_set_show_hidden (GtkFileSystemModel *model,
     }
 }
 
+/**
+ * _gtk_file_system_model_set_show_folders:
+ * @model: a #GtkFileSystemModel
+ * @show_folders: whether folders should be displayed
+ * 
+ * Sets whether folders should be included in the #GtkTreeModel for
+ * display.
+ **/
 void
 _gtk_file_system_model_set_show_folders (GtkFileSystemModel *model,
 					 gboolean            show_folders)
@@ -661,6 +700,15 @@ _gtk_file_system_model_set_show_folders (GtkFileSystemModel *model,
     }
 }
 
+/**
+ * _gtk_file_system_model_set_show_files:
+ * @model: a #GtkFileSystemModel
+ * @show_files: whether files (as opposed to folders) should
+ *              be displayed.
+ * 
+ * Sets whether files (as opposed to folders) should be included
+ * in the #GtkTreeModel for display.
+ **/
 void
 _gtk_file_system_model_set_show_files (GtkFileSystemModel *model,
 				       gboolean            show_files)
@@ -679,6 +727,22 @@ _gtk_file_system_model_set_show_files (GtkFileSystemModel *model,
     }
 }
 
+/**
+ * _gtk_file_system_model_get_info:
+ * @model: a #GtkFileSystemModel
+ * @iter: a #GtkTreeIter pointing to a row of @model
+ * 
+ * Gets the #GtkFileInfo structure for a particular row
+ * of @model. The information included in this structure
+ * is determined by the @types parameter to
+ * _gtk_file_system_model_new().
+ * 
+ * Return value: a #GtkFileInfo structure. This structure
+ *   is owned by @model and must not be modified or freed.
+ *   If you want to save the information for later use,
+ *   you must make a copy, since the structure may be
+ *   freed on later changes to the file system.
+ **/
 const GtkFileInfo *
 _gtk_file_system_model_get_info (GtkFileSystemModel *model,
 				 GtkTreeIter        *iter)
@@ -686,6 +750,18 @@ _gtk_file_system_model_get_info (GtkFileSystemModel *model,
   return file_model_node_get_info (model, iter->user_data);
 }
 
+/**
+ * _gtk_file_system_model_get_uri:
+ * @model: a #GtkFileSystemModel
+ * @iter: a #GtkTreeIter pointing to a row of @model
+ * 
+ * Gets the URI for a particular row in @model. 
+ *
+ * Return value: the URI. This string is owned by @model and
+ *   or freed. If you want to save the URI for later use,
+ *   you must make a copy, since the string may be freed
+ *   on later changes to the file system.
+ **/
 const gchar *
 _gtk_file_system_model_get_uri (GtkFileSystemModel *model,
 				GtkTreeIter        *iter)
@@ -749,6 +825,32 @@ find_and_ref_uri (GtkFileSystemModel *model,
   return FALSE;
 }
 
+/**
+ * _gtk_file_system_model_uri_do:
+ * @model: a #GtkFileSystemModel
+ * @uri: a URI pointing to a file in the filesystem
+ *       for @model.
+ * @func: Function to call with the path and iter corresponding
+ *        to @uri.
+ * @user_data: data to pass to @func
+ * 
+ * Locates @uri within @model, referencing
+ * (gtk_tree_model_ref_node ()) all parent nodes,
+ * calls @func passing in the path and iter for @uri,
+ * then unrefs all the parent nodes.
+ *
+ * The reason for doing this operation as a callback
+ * is so that if the operation performed with the the
+ * path and iter results in referencing the the node
+ * and/or parent nodes, we don't load all the information
+ * about the nodes.
+ *
+ * This function is particularly useful for expanding
+ * a #GtkTreeView to a particular point in the file system.
+ * 
+ * Return value: %TRUE if the URI was successfully
+ *  found in @model and @func was called.
+ **/
 gboolean
 _gtk_file_system_model_uri_do (GtkFileSystemModel       *model,
 			       const gchar              *uri,
@@ -873,7 +975,7 @@ file_model_node_free (FileModelNode *node)
   g_free (node);
 }
 
-const GtkFileInfo *
+static const GtkFileInfo *
 file_model_node_get_info (GtkFileSystemModel *model,
 			  FileModelNode      *node)
 {
diff --git a/gtk/gtkfilesystemunix.c b/gtk/gtkfilesystemunix.c
index 9e42ef978f..dfed7d5ccb 100644
--- a/gtk/gtkfilesystemunix.c
+++ b/gtk/gtkfilesystemunix.c
@@ -154,6 +154,21 @@ _gtk_file_system_unix_get_type (void)
   return file_system_unix_type;
 }
 
+/**
+ * _gtk_file_system_unix_new:
+ * 
+ * Creates a new #GtkFileSystemUnix object. #GtkFileSystemUnix
+ * implements the #GtkFileSystem interface with direct access to
+ * the filesystem using Unix/Linux API calls
+ * 
+ * Return value: the new #GtkFileSystemUnix object
+ **/
+GtkFileSystem *
+_gtk_file_system_unix_new (void)
+{
+  return g_object_new (GTK_TYPE_FILE_SYSTEM_UNIX, NULL);
+}
+
 static void
 gtk_file_system_unix_class_init (GtkFileSystemUnixClass *class)
 {
diff --git a/gtk/gtkfilesystemunix.h b/gtk/gtkfilesystemunix.h
index 03d816efea..3c9904144d 100644
--- a/gtk/gtkfilesystemunix.h
+++ b/gtk/gtkfilesystemunix.h
@@ -31,8 +31,9 @@ G_BEGIN_DECLS
 
 typedef struct _GtkFileSystemUnix      GtkFileSystemUnix;
 
-GType _gtk_file_system_unix_get_type (void);
-
+GtkFileSystem *_gtk_file_system_unix_new       (void);
+GType          _gtk_file_system_unix_get_type (void);
+     
 G_END_DECLS
 
 #endif /* __GTK_FILE_SYSTEM_UNIX_H__ */