cleanup: remove overly excessive comments

Signed-off-by: David Oberhollenzer <david.oberhollenzer@sigma-star.at>

1 files changed, 116 insertions, 284 deletions

diff --git a/include/fstree.h b/include/fstree.h
index 4986ec2..27cb39d 100644
--- a/include/fstree.h
+++ b/include/fstree.h
@@ -19,238 +19,146 @@ typedef struct dir_info_t dir_info_t;
 typedef struct fstree_t fstree_t;
 typedef struct tree_xattr_t tree_xattr_t;
 
-/**
- * @struct tree_xattr_t
- *
- * @brief Encapsulates a set of key-value pairs attached to a @ref tree_node_t
- */
+/* Encapsulates a set of key-value pairs attached to a tree_node_t */
 struct tree_xattr_t {
+	/* Number of key-value pairs */
 	size_t num_attr;
+
+	/* Total size of the array, i.e. it's capacity */
 	size_t max_attr;
 
+	/* Offset of the meta data block where the pairs are stored */
 	uint64_t block;
+
+	/* Offset into a meta data block where the pairs start */
 	uint32_t offset;
+
+	/* Number of bytes written to disk */
 	uint32_t size;
 
-	/**
-	 * @brief Incremental index within all xattr blocks
-	 */
+	/* Incremental index within all xattr blocks */
 	size_t index;
 
-	/**
-	 * @brief Back reference to the tree node this was created for
-	 */
+	/* Back reference to the tree node this was created for */
 	tree_node_t *owner;
 
-	/**
-	 * @brief linked list pointer of list of attributes in @ref fstree_t
-	 */
+	/* linked list pointer of list of attributes in @ref fstree_t */
 	tree_xattr_t *next;
 
-	/**
-	 * @brief An array with pairs of key-value tupples
-	 *
-	 * Each key-value tupple is encoded as (key << 32) | value.
-	 */
+	/* Array with pairs of key-value tupples.
+	   Each key-value tupple is encoded as (key << 32) | value. */
 	uint64_t ref[];
 };
 
-/**
- * @struct file_info_t
- *
- * @brief Additional meta data stored in a @ref tree_node_t for regular files
- */
+/* Additional meta data stored in a tree_node_t for regular files. */
 struct file_info_t {
+	/* Path to the input file. */
 	char *input_file;
 
-	/**
-	 * @brief Linked list pointer for aggregating fragments
-	 *
-	 * When writing out data blocks, files that don't have a multiple of
-	 * the block size have their tail ends gathered in a fragment block.
-	 * A linked list is used to keep track of which files share the same
-	 * fragment block.
-	 */
+	/* Linked list pointer for aggregating fragments
+
+	   When writing out data blocks, files that don't have a multiple of
+	   the block size have their tail ends gathered in a fragment block.
+	   A linked list is used to keep track of which files share the same
+	   fragment block. */
 	file_info_t *frag_next;
 
-	/**
-	 * @brief Total size of the file in bytes
-	 */
 	uint64_t size;
 
-	/**
-	 * @brief Absolute position of the first data block
-	 */
+	/* Absolute position of the first data block. */
 	uint64_t startblock;
 
-	/**
-	 * @brief Fragment index
-	 *
-	 * If the size is not a multiple of the block size, this holds an
-	 * index into the fragment table.
-	 */
+	/* If the size is not a multiple of the block size, this holds an
+	   index into the fragment table. */
 	uint32_t fragment;
 
-	/**
-	 * @brief Byte offset into the fragment block
-	 *
-	 * If the size is not a multiple of the block size, this holds an
-	 * offset into the fragment block.
-	 */
+	/* Byte offset into the fragment block. */
 	uint32_t fragment_offset;
 
-	/**
-	 * @brief Stores the compressed file block sizes
-	 *
-	 * For each full data block, stores the compressed size. Bit number
-	 * 24 is set if the block is stored uncompressed.
-	 */
+	/* For each full data block, stores the compressed size.
+	   Bit (1 << 24) is set if the block is stored uncompressed. */
 	uint32_t blocksizes[];
 };
 
-/**
- * @struct dir_info_t
- *
- * @brief Additional meta data stored in a @ref tree_node_t for directories
- */
+/* Additional meta data stored in a tree_node_t for directories */
 struct dir_info_t {
-	/**
-	 * @brief Pointer to the head of the linked list of children
-	 */
+	/* Linked list head for children in the directory */
 	tree_node_t *children;
 
-	/**
-	 * @brief Size of the directory
-	 *
-	 * Computed and updated on the fly while writing directory
-	 * meta data to disk.
-	 */
+	/* Size on disk. Computed and updated on the fly while writing
+	   directory meta data to disk. */
 	uint64_t size;
 
-	/**
-	 * @brief Start block offset, relative to directory table start
-	 *
-	 * Offset of the compressed meta data block where the directory
-	 * listing is stored in the SquashFS image.
-	 */
+	/* Start block offset, relative to directory table start. */
 	uint64_t start_block;
 
-	/**
-	 * @brief Byte offset into the uncompressed meta data block
-	 *
-	 * Points at where in the meta data block the directory listing begins.
-	 */
+	/* Byte offset into the uncompressed meta data block. */
 	uint32_t block_offset;
 
-	/**
-	 * @brief Set to true for implicitly generated directories
-	 */
+	/* Set to true for implicitly generated directories.  */
 	bool created_implicitly;
 };
 
-/**
- * @struct tree_node_t
- *
- * @brief A node in a file system tree
- */
+/* A node in a file system tree */
 struct tree_node_t {
-	/**
-	 * @brief Linked list pointer to the next node in the same directory
-	 */
+	/* Parent directory children linked list pointer. */
 	tree_node_t *next;
 
-	/**
-	 * @brief Pointer to directory node that this node is in
-	 *
-	 * This is NULL only for the root node
-	 */
+	/* Root node has this set to NULL. */
 	tree_node_t *parent;
 
-	/**
-	 * @brief Pointer into the payload area where the node name is stored
-	 *
-	 * For the root node, this points to an empty string
-	 */
+	/* For the root node, this points to an empty string. */
 	char *name;
 
-	/**
-	 * @brief A pointer to an extended attribute array or NULL if unused
-	 */
+	/*
+	  A pointer to an extended attribute array or NULL if unused.
+
+	  This field is not stored in-line and taken care of by the generic
+	  fstree cleanup code, since it is generatde after the tree already
+	  exists and shared across multiple nodes.
+	*/
 	tree_xattr_t *xattr;
 
 	uint32_t uid;
 	uint32_t gid;
 	uint16_t mode;
 
-	/**
-	 * @brief SquashFS inode refernce number
-	 *
-	 * This is computed and stored here on the fly when writing inodes
-	 * generated from tree nodes to the SquashFS image.
-	 *
-	 * An inode reference is the 32 bit offset of the compressed meta data
-	 * block, shifted left by 16 and ored with a 13 bit offset into the
-	 * uncompressed meta data block.
-	 */
+	/* SquashFS inode refernce number. 32 bit offset of the meta data
+	   block start (relative to inode table start), shifted left by 16
+	   and ored with a 13 bit offset into the uncompressed meta data block.
+
+	   Generated on the fly when writing inodes. */
 	uint64_t inode_ref;
 
-	/**
-	 * @brief inode number
-	 *
-	 * This is computed and stored here on the fly when writing inodes
-	 * generated from tree nodes to the SquashFS image.
-	 */
+	/* Inode number. Generated on the fly when writing inodes. */
 	uint32_t inode_num;
 
-	/**
-	 * @brief SquashFS inode type used for this tree node
-	 *
-	 * This is computed and stored here on the fly when writing inodes
-	 * generated from tree nodes to the SquashFS image. It can't be
-	 * easily determined in advance since it depends also on the size
-	 * of the node, which means for directories the size of the directory
-	 * entries once written to disk.
-	 *
-	 * All code that actually processes tree nodes should use the mode
-	 * field instead (mode & S_IFMT gives us the node type). It is stored
-	 * here when generating inodes since we need it later on to generate
-	 * directory entries.
-	 */
+	/* SquashFS inode type used for this tree node.
+
+	   Generated on the fly when writing inodes. It can't be easily
+	   determined in advance since it depends also on the size of the
+	   node, which means for directories the size of the directory
+	   entries once written to disk.
+
+	   All code that actually processes tree nodes should use the mode
+	   field instead (mode & S_IFMT gives us the node type). It is stored
+	   here when generating inodes since we need it later on to generate
+	   directory entries.
+	*/
 	int type;
 
+	/* Type specific data. Pointers are into payload area blow. */
 	union {
-		/**
-		 * @brief Pointer into payload area storing directory meta data
-		 */
 		dir_info_t *dir;
-
-		/**
-		 * @brief Pointer into payload area storing file meta data
-		 */
 		file_info_t *file;
-
-		/**
-		 * @brief Pointer into payload area storing symlink target
-		 */
 		char *slink_target;
-
-		/**
-		 * @brief A device number for device special files
-		 */
 		uint64_t devno;
 	} data;
 
-	/**
-	 * @brief Additional data stored in the tree node
-	 */
 	uint8_t payload[];
 };
 
-/**
- * @struct fstree_t
- *
- * @brief Encapsulates a file system tree
- */
+/* Encapsulates a file system tree */
 struct fstree_t {
 	uint32_t default_uid;
 	uint32_t default_gid;
@@ -265,157 +173,81 @@ struct fstree_t {
 	tree_xattr_t *xattr;
 };
 
-/**
- * @brief Initialize an fstree object
- *
- * @memberof fstree_t
- *
- * Initializing means copying over the default values and creating a root node.
- * On error, an error message is written to stderr.
- *
- * @param fs           A pointer to an uninitialized fstree object
- * @param block_size   The data block size for regular files
- * @param mtime        Default modification time stamp to use on all nodes
- * @param default_mode Default permission bits to use on implicitly created
- *                     directories.
- * @param default_uid  Default UID to set on implicitly created directories.
- * @param default_gid  Default GID to set on implicitly created directories.
- *
- * @return Zero on success, -1 on failure
- */
+/*
+  Initializing means copying over the default values and creating a root node.
+  On error, an error message is written to stderr.
+
+  `block_size` is the the data block size for regular files.
+
+  Returns 0 on success.
+*/
 int fstree_init(fstree_t *fs, size_t block_size, uint32_t mtime,
 		uint16_t default_mode, uint32_t default_uid,
 		uint32_t default_gid);
 
-/**
- * @brief Clean up an fstree object and free all memory it uses
- *
- * @memberof fstree_t
- *
- * This function also recursively frees all tree nodes.
- *
- * @param fs A pointer to an fstree object
- */
 void fstree_cleanup(fstree_t *fs);
 
-/**
- * @brief Add a generic node to an fstree object
- *
- * @memberof fstree_t
- *
- * The new node is inserted by path. If some components of the path don't
- * exist, they are created as directories with default permissions, like
- * mkdir -p would, and marked as implcitily created. A subsequent call that
- * tries to create an existing tree node will fail, except if the target
- * is an implicitly created directory node and the call tries to create it
- * as a directory. This will simply overwrite the permissions and ownership.
- * The implicitly created flag is then cleared and subsequent attempts to
- * create this directory again will also fail.
- *
- * This function does not print anything to stderr, instead it sets an
- * appropriate errno value.
- *
- * @param fs        A pointer to an fstree object
- * @param path      The path of the new object to insert
- * @param mode      Specifies both access permission and what kind of node
- *                  to create
- * @param uid       The user id that owns the new node
- * @param gid       The group id that owns the new node
- * @param extra_len An additional number of bytes to allocate for payload data
- *
- * @return A pointer to the new tree node or NULL on failure
- */
+/*
+  Add a generic node to an fstree.
+
+  The new node is inserted by path. If some components of the path don't
+  exist, they are created as directories with default permissions, like
+  mkdir -p would, and marked as implcitily created. A subsequent call that
+  tries to create an existing tree node will fail, except if the target
+  is an implicitly created directory node and the call tries to create it
+  as a directory (this will simply overwrite the permissions and ownership).
+  The implicitly created flag is then cleared. Subsequent attempts to create
+  an existing directory again will then also fail.
+
+  This function does not print anything to stderr, instead it sets an
+  appropriate errno value.
+
+  `extra_len` specifies an additional number of bytes to allocate for payload
+  data in the tree node.
+*/
 tree_node_t *fstree_add(fstree_t *fs, const char *path, uint16_t mode,
 			uint32_t uid, uint32_t gid, size_t extra_len);
 
-/**
- * @brief A wrappter around @ref fstree_add for regular files
- *
- * @memberof fstree_t
- *
- * This function internally computes the number of extra payload bytes
- * requiered and sets up the payload pointers propperly, as they are
- * different than for other types of nodes.
- *
- * @return A pointer to the new tree node or NULL on failure
- */
+/*
+  A wrappter around fstree_add for regular files.
+
+  This function internally computes the number of extra payload bytes
+  requiered and sets up the payload pointers propperly.
+*/
 tree_node_t *fstree_add_file(fstree_t *fs, const char *path, uint16_t mode,
 			     uint32_t uid, uint32_t gid, uint64_t filesz,
 			     const char *input);
 
-/**
- * @brief Add an extended attribute key value pair to a tree node
- *
- * @memberof fstree_t
- *
- * @param fs    A pointer to the fstree object
- * @param node  A pointer to the tree node to attach attributes to
- * @param key   The xattr key with namespace prefix
- * @param value The xattr value string
- *
- * @return Zero on success, -1 on failure (prints error to stderr)
- */
+/*
+  Add an extended attribute key value pair to a tree node.
+
+  Returns 0 on success, prints error to stderr on failure.
+*/
 int fstree_add_xattr(fstree_t *fs, tree_node_t *node,
 		     const char *key, const char *value);
 
-/**
- * @brief Recompute index number of all xattr blocks
- *
- * @memberof fstree_t
- *
- * @param fs A pointer to the fstree object
- */
+/* Recompute running index number of all xattr blocks. */
 void fstree_xattr_reindex(fstree_t *fs);
 
-/**
- * @brief Remove dupliciate xattr listings
- *
- * @memberof fstree_t
- *
- * If two tree nodes have pointers to distinct @ref tree_xattr_t listings that
- * turn out to be equivalent, throw one of the two away and make both nodes
- * point to the same instance.
- */
+/* Sort and dedupliciate xattr blocks, then recumpute the index numbers. */
 void fstree_xattr_deduplicate(fstree_t *fs);
 
-/**
- * @brief Load an fstree from a text file describing it
- *
- * @memberof fstree_t
- *
- * This function parses the file format accepted by gensquashfs and restores
- * a file system tree from it.
- *
- * On failure, an error report with filename and line number is written
- * to stderr.
- *
- * @param fs       A pointer to an fstree object that is already initialized
- *                 prior to calling this function.
- * @param filename The path to the input file to process.
- *
- * @return Zero on success, -1 on failure.
+/*
+  Parses the file format accepted by gensquashfs and produce a file system
+  tree from it.
+
+  On failure, an error report with filename and line number is written
+  to stderr.
+
+  Returns 0 on success.
  */
 int fstree_from_file(fstree_t *fs, const char *filename);
 
-/**
- * @brief Lexicographically sort all directory contents
- *
- * @memberof fstree_t
- *
- * @param fs A pointer to an fstree object
- */
+/* Lexicographically sort all directory contents. */
 void fstree_sort(fstree_t *fs);
 
-/**
- * @brief Add labels from an SELinux labeling file to all tree nodes
- *
- * @memberof fstree_t
- *
- * @param fs       A pointer to an fstree object
- * @param filename The name of the SELinux context file
- *
- * @return Zero on success, -1 on failure
- */
+/* Add labels from an SELinux labeling file to all tree nodes.
+   Returns 0 on success. Internally prints errors to stderr. */
 int fstree_relabel_selinux(fstree_t *fs, const char *filename);
 
 #endif /* FSTREE_H */