libostree: Fix many gtk-doc warnings

doc/Makefile.am

@@ -34,7 +34,7 @@ DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml
 # gtk-doc will search all .c & .h files beneath here for inline comments
 # documenting the functions and macros.
 # e.g. DOC_SOURCE_DIR=../../../gtk
-DOC_SOURCE_DIR=$(top_srcdir)/src
+DOC_SOURCE_DIR=$(top_srcdir)/src/libostree
 
 # Extra options to pass to gtkdoc-scangobj. Not normally needed.
 SCANGOBJ_OPTIONS= --version

src/libostree/ostree-chain-input-stream.c

@@ -68,7 +68,7 @@ ostree_chain_input_stream_class_init (OstreeChainInputStreamClass *klass)
   stream_class->read_fn = ostree_chain_input_stream_read;
   stream_class->close_fn = ostree_chain_input_stream_close;
 
-  /**
+  /*
    * OstreeChainInputStream:streams: (element-type GInputStream)
    *
    * Chain of input streams read in order.

src/libostree/ostree-checksum-input-stream.c

@@ -61,7 +61,7 @@ ostree_checksum_input_stream_class_init (OstreeChecksumInputStreamClass *klass)
 
   stream_class->read_fn = ostree_checksum_input_stream_read;
 
-  /**
+  /*
    * OstreeChecksumInputStream:checksum:
    *
    * The checksum that the stream updates.

src/libostree/ostree-core.c

@@ -75,7 +75,7 @@ ostree_metadata_variant_type (OstreeObjectType objtype)
 /**
  * ostree_validate_checksum_string:
  * @sha256: SHA256 hex string
- * @error:
+ * @error: Error
  *
  * Use this function to see if input strings are checksums.
  *
@@ -96,7 +96,7 @@ ostree_validate_checksum_string (const char *sha256,
  * @refspec: A "refspec" string
  * @out_remote: (out) (allow-none): The remote name, or %NULL if the refspec refs to a local ref
  * @out_ref: (out) (allow-none): Name of ref
- * @error:
+ * @error: Error
  *
  * Split a refspec like "gnome-ostree:gnome-ostree/buildmaster" into
  * two parts; @out_remote will be set to "gnome-ostree", and @out_ref
@@ -262,8 +262,8 @@ read_xattr_name_array (const char *path,
  * ostree_get_xattrs_for_file:
  * @f: a #GFile
  * @out_xattrs: (out): A new #GVariant containing the extended attributes
- * @cancellable:
+ * @cancellable: Cancellable
- * @error:
+ * @error: Error
  *
  * Read all extended attributes of @f in a canonical sorted order, and
  * set @out_xattrs with the result.
@@ -441,8 +441,8 @@ write_padding (GOutputStream    *output,
  * @variant: A variant
  * @alignment_offset: Used to determine whether or not we should write padding bytes
  * @checksum: (allow-none): If provided, update with written data
- * @cancellable:
+ * @cancellable: Cancellable
- * @error:
+ * @error: Error
  *
  * Use this function for serializing a chain of 1 or more variants
  * into a stream; the @alignment_offset parameter is used to ensure
@@ -503,8 +503,8 @@ ostree_write_variant_with_size (GOutputStream      *output,
  * @out: Stream
  * @variant: A variant, should be a file header
  * @checksum: (allow-none): If provided, update with written data
- * @cancellable:
+ * @cancellable: Cancellable
- * @error:
+ * @error: Error
  *
  * Write a file header variant to the provided @out stream, optionally
  * updating @checksum.
@@ -535,8 +535,8 @@ ostree_write_file_header_update_checksum (GOutputStream         *out,
  * @xattrs: (allow-none): Optional extended attributes
  * @out_input: (out): Serialized object stream
  * @out_length: (out): Length of stream
- * @cancellable:
+ * @cancellable: Cancellable
- * @error:
+ * @error: Error
  *
  * Convert from a "bare" file representation into an
  * OSTREE_OBJECT_TYPE_FILE stream.  This is a fundamental operation
@@ -600,8 +600,8 @@ ostree_raw_file_to_content_stream (GInputStream       *input,
  * @out_input: (out): The raw file content stream
  * @out_file_info: (out): Normal metadata 
  * @out_xattrs: (out): Extended attributes
- * @cancellable:
+ * @cancellable: Cancellable
- * @error:
+ * @error: Error
  *
  * The reverse of ostree_raw_file_to_content_stream(); this function
  * converts an object content stream back into components.
@@ -713,8 +713,8 @@ ostree_content_stream_parse (gboolean                compressed,
  * @out_input: (out): The raw file content stream
  * @out_file_info: (out): Normal metadata 
  * @out_xattrs: (out): Extended attributes
- * @cancellable:
+ * @cancellable: Cancellable
- * @error:
+ * @error: Error
  *
  * A thin wrapper for ostree_content_stream_parse(); this function
  * converts an object content stream back into components.
@@ -978,8 +978,8 @@ ostree_create_directory_metadata (GFileInfo    *dir_info,
  * ostree_set_xattrs:
  * @f: a file
  * @xattrs: Extended attribute list
- * @cancellable:
+ * @cancellable: Cancellable
- * @error:
+ * @error: Error
  *
  * For each attribute in @xattrs, replace the value (if any) of @f for
  * that attribute.  This function does not clear other existing

src/libostree/ostree-core.h

@@ -26,7 +26,6 @@
 
 G_BEGIN_DECLS
 
-
 /**
  * OSTREE_MAX_METADATA_SIZE:
  * 
@@ -43,6 +42,10 @@ G_BEGIN_DECLS
 
 /**
  * OstreeObjectType:
+ * @OSTREE_OBJECT_TYPE_FILE: Content; regular file, symbolic link
+ * @OSTREE_OBJECT_TYPE_DIR_TREE: List of children (trees or files), and metadata
+ * @OSTREE_OBJECT_TYPE_DIR_META: Directory metadata
+ * @OSTREE_OBJECT_TYPE_COMMIT: Toplevel object, refers to tree and dirmeta for root
  *
  * Enumeration for core object types; %OSTREE_OBJECT_TYPE_FILE is for
  * content, the other types are metadata.
@@ -56,10 +59,12 @@ typedef enum {
 
 /**
  * OSTREE_OBJECT_TYPE_IS_META:
+ * @t: An #OstreeObjectType
  *
  * Returns: %TRUE if object type is metadata
  */
 #define OSTREE_OBJECT_TYPE_IS_META(t) (t >= 2 && t <= 4)
+
 /**
  * OSTREE_OBJECT_TYPE_LAST:
  *
@@ -67,7 +72,6 @@ typedef enum {
  */
 #define OSTREE_OBJECT_TYPE_LAST OSTREE_OBJECT_TYPE_COMMIT
 
-
 /**
  * OSTREE_FILE_HEADER_GVARIANT_FORMAT:
  *

src/libostree/ostree-mutable-tree.c

@@ -223,7 +223,7 @@ ostree_mutable_tree_lookup (OstreeMutableTree   *self,
 
 /**
  * ostree_mutable_tree_ensure_parent_dirs:
- * @self:
+ * @self: Tree
  * @split_path: (element-type utf8): File path components
  * @metadata_checksum: SHA256 checksum for metadata
  * @out_parent: (out) (transfer full): The parent tree
@@ -282,11 +282,11 @@ ostree_mutable_tree_ensure_parent_dirs (OstreeMutableTree  *self,
 
 /**
  * ostree_mutable_tree_walk:
- * @self:
+ * @self: Tree
  * @split_path: (element-type utf8): Split pathname
  * @start: Descend from this number of elements in @split_path
  * @out_subdir: (out) (transfer full): Target parent
- * @error:
+ * @error: Error
  *
  * Traverse @start number of elements starting from @split_path; the
  * child will be returned in @out_subdir.

src/libostree/ostree-repo-pull.c

@@ -20,7 +20,7 @@
  * Author: Colin Walters <walters@verbum.org>
  */
 
-/**
+/*
  * See:
  * https://mail.gnome.org/archives/ostree-list/2012-August/msg00021.html
  *

src/libostree/ostree-repo-refs.c

@@ -353,11 +353,11 @@ resolve_refspec (OstreeRepo     *self,
 
 /**
  * ostree_repo_resolve_rev:
- * @self:
+ * @self: Repo
  * @refspec: A refspec
  * @allow_noent: Do not throw an error if refspec does not exist
  * @out_rev: (out) (transfer full): A checksum,or %NULL if @allow_noent is true and it does not exist
- * @error:
+ * @error: Error
  *
  * Look up the given refspec, returning the checksum it references in
  * the parameter @out_rev.

src/libostree/ostree-repo.c

@@ -226,7 +226,7 @@ ostree_repo_copy_config (OstreeRepo *self)
 
 /**
  * ostree_repo_write_config:
- * @self:
+ * @self: Repo
  * @new_config: Overwrite the config file with this data.  Do not change later!
  * @error: a #GError
  *
@@ -395,7 +395,7 @@ ostree_repo_get_mode (OstreeRepo  *self)
 
 /**
  * ostree_repo_get_parent:
- * @self:
+ * @self: Repo
  * 
  * Before this function can be used, ostree_repo_init() must have been
  * called.
@@ -1680,12 +1680,12 @@ stage_directory_to_mtree_internal (OstreeRepo                  *self,
 
 /**
  * ostree_repo_stage_directory_to_mtree:
- * @self:
+ * @self: Repo
  * @dir: Path to a directory
  * @mtree: Overlay directory contents into this tree
  * @modifier: (allow-none): Optional modifier
- * @cancellable:
+ * @cancellable: Cancellable
- * @error:
+ * @error: Error
  *
  * Store objects for @dir and all children into the repository @self,
  * overlaying the resulting filesystem hierarchy into @mtree.
@@ -2191,11 +2191,11 @@ ostree_repo_has_object (OstreeRepo           *self,
 
 /**
  * ostree_repo_delete_object:
- * @self:
+ * @self: Repo
  * @objtype: Object type
  * @sha256: Checksum
- * @cancellable:
+ * @cancellable: Cancellable
- * @error:
+ * @error: Error
  *
  * Remove the object of type @objtype with checksum @sha256
  * from the repository.  An error of type %G_IO_ERROR_NOT_FOUND
@@ -2214,12 +2214,12 @@ ostree_repo_delete_object (OstreeRepo           *self,
 
 /**
  * ostree_repo_query_object_storage_size:
- * @self:
+ * @self: Repo
  * @objtype: Object type
  * @sha256: Checksum
  * @out_size: (out): Size in bytes object occupies physically
- * @cancellable:
+ * @cancellable: Cancellable
- * @error:
+ * @error: Error
  *
  * Return the size in bytes of object with checksum @sha256, after any
  * compression has been applied.
@@ -2286,11 +2286,11 @@ ostree_repo_load_variant_if_exists (OstreeRepo       *self,
 
 /**
  * ostree_repo_load_variant:
- * @self:
+ * @self: Repo
  * @objtype: Expected object type
  * @sha256: Checksum string
  * @out_variant: (out): (transfer full): Metadata object
- * @error:
+ * @error: Error
  * 
  * Load the metadata object @sha256 of type @objtype, storing the
  * result in @out_variant.
@@ -2308,11 +2308,11 @@ ostree_repo_load_variant (OstreeRepo       *self,
 
 /**
  * ostree_repo_list_objects:
- * @self:
+ * @self: Repo
- * @flags:
+ * @flags: Flags controlling enumeration
  * @out_objects: (out): Map of serialized object name to variant data
- * @cancellable:
+ * @cancellable: Cancellable
- * @error:
+ * @error: Error
  *
  * This function synchronously enumerates all objects in the
  * repository, returning data in @out_objects.  @out_objects

src/libotutil/ot-variant-utils.c

@@ -102,10 +102,15 @@ ot_util_variant_take_ref (GVariant *variant)
 }
 
 /**
- * Return in @out_variant the result of memory-mapping the entire
+ * ot_util_variant_map:
- * contents of file @src.
+ * @src: a #GFile
+ * @type: Use this for variant
+ * @trusted: See documentation of g_variant_new_from_data()
+ * @out_variant: (out): Return location for new variant
+ * @error:
  *
- * Note the returned @out_variant is not floating.
+ * Memory-map @src, and store a new #GVariant referring to this memory
+ * in @out_variant.  Note the returned @out_variant is not floating.
  */
 gboolean
 ot_util_variant_map (GFile              *src,

src/ostree/ot-admin-functions.c

@@ -360,10 +360,15 @@ parse_kernel_commandline (OtOrderedHash  **out_args,
 
 /**
  * ot_admin_find_booted_deployment:
+ * @target_sysroot: Root directory
+ * @deployments: (element-type OtDeployment): Loaded deployments
+ * @out_deployment: (out): The currently booted deployment
+ * @cancellable:
+ * @error: 
  * 
- * Returns in @out_deployment the currently booted deployment using
+ * If the system is currently booted into a deployment in
- * the list in @deployments.  Will always return %NULL if
+ * @deployments, set @out_deployment.  Note that if @target_sysroot is
- * @target_sysroot is not equal to "/".
+ * not equal to "/", @out_deployment will always be set to %NULL.
  */
 gboolean
 ot_admin_find_booted_deployment (GFile               *target_sysroot,