faux.file: Doxygen documentation

faux/file/file.c

@@ -32,8 +32,9 @@
 
 /** @brief Create file object using existent fd.
  *
- * Create file object an link it to existent file descriptor.
+ * Create file object and link it to existent file descriptor.
  *
+ * @param [in] fd Already opened file descriptor.
  * @return Allocated and initialized file object or NULL on error.
  */
 faux_file_t *faux_file_fdopen(int fd) {
@@ -67,6 +68,19 @@ faux_file_t *faux_file_fdopen(int fd) {
 }
 
 
+/** @brief Create file object and open correspondent file.
+ *
+ * Function opens specified file using flags and create file object based
+ * on this opened file. The object must be freed and file must be closed
+ * later by the faux_file_close().
+ *
+ * @warning The faux_file_close() must be executed later to free file object.
+ *
+ * @param [in] pathname File name.
+ * @param [in] flags Flags to open file (like O_RDONLY etc).
+ * @param [in] mode File permissions if file will be created.
+ * @return File object or NULL on error.
+ */
 faux_file_t *faux_file_open(const char *pathname, int flags, mode_t mode) {
 
 	int fd = -1;
@@ -83,6 +97,14 @@ faux_file_t *faux_file_open(const char *pathname, int flags, mode_t mode) {
 }
 
 
+/** @brief Closes file and frees file object.
+ *
+ * Function closes previously opened (by faux_file_open() or faux_file_fdopen())
+ * file and frees file object structures.
+ *
+ * @param [in] f File object to close and free.
+ * @return 0 - success, < 0 - error
+ */
 int faux_file_close(faux_file_t *f) {
 
 	int fd = -1;
@@ -99,6 +121,13 @@ int faux_file_close(faux_file_t *f) {
 }
 
 
+/** @brief Returns file descriptor from file object.
+ *
+ * Works like fileno() function for stream objects.
+ *
+ * @param [in] f File object.
+ * @return Linked file descriptor.
+ */
 int faux_file_fileno(faux_file_t *f) {
 
 	assert(f);
@@ -109,6 +138,11 @@ int faux_file_fileno(faux_file_t *f) {
 }
 
 
+/** @brief Returns EOF flag.
+ *
+ * @param [in] f File object
+ * @return BOOL_TRUE if it's end of file and BOOL_FALSE else.
+ */
 bool_t faux_file_eof(const faux_file_t *f) {
 
 	assert(f);
@@ -119,6 +153,21 @@ bool_t faux_file_eof(const faux_file_t *f) {
 }
 
 
+/** @brief Service static function to take away data block from internal buffer.
+ *
+ * Returns allocated data block in a form of C-string i.e. adds '\0' at the end
+ * of data. Additionally function can drop some bytes from internal buffer.
+ * It's usefull when it's necessary to get text string from the buffer and
+ * drop trailing end of line.
+ *
+ * @warning Returned pointer must be freed by faux_str_free() later.
+ *
+ * @param [in] f File object.
+ * @param [in] bytes_get Number of bytes to get from internal buffer.
+ * @param [in] bytes_drop Number of bytes to drop. Actually
+ * (bytes_drop + bytes_get) bytes will be removed from internal buffer.
+ * @return Allocated string (with trailing '\0') with data to get.
+ */
 static char *faux_file_takeaway(faux_file_t *f,
 	size_t bytes_get, size_t bytes_drop) {
 
@@ -148,6 +197,16 @@ static char *faux_file_takeaway(faux_file_t *f,
 }
 
 
+/** @brief Service static function to get all data from buf as single C-string.
+ *
+ * Gets all the data from internal buffer as a single C-string (i.e. ends with
+ * '\0'). This data will be removed from internal buffer.
+ *
+ * @warning Returned pointer must be freed by faux_str_free() later.
+ *
+ * @param [in] f File object.
+ * @return Allocated string (with trailing '\0') with data to get.
+ */
 static char *faux_file_takeaway_rest(faux_file_t *f) {
 
 	assert(f);
@@ -158,6 +217,17 @@ static char *faux_file_takeaway_rest(faux_file_t *f) {
 }
 
 
+/** @brief Service static function to get line from buf as single C-string.
+ *
+ * Gets line (data ends with EOL) from internal buffer as a single C-string
+ * (i.e. ends with '\0'). The resulting line will not contain trailing EOL but
+ * EOL will be removed from internal buffer together with line.
+ *
+ * @warning Returned pointer must be freed by faux_str_free() later.
+ *
+ * @param [in] f File object.
+ * @return Allocated string (with trailing '\0') with line.
+ */
 static char *faux_file_takeaway_line(faux_file_t *f) {
 
 	char *find = NULL;
@@ -179,6 +249,14 @@ static char *faux_file_takeaway_line(faux_file_t *f) {
 }
 
 
+/** @brief Service static function to enlarge internal buffer.
+ *
+ * The initial size of internal buffer is 128 bytes. Each function execution
+ * enlarges buffer by chunk of 128 bytes.
+ *
+ * @param [in] f File objects.
+ * @return 0 - success, < 0 - error
+ */
 static int faux_file_enlarge_buffer(faux_file_t *f) {
 
 	size_t new_size = 0;
@@ -202,6 +280,17 @@ static int faux_file_enlarge_buffer(faux_file_t *f) {
 }
 
 
+/** @brief Read line from file.
+ *
+ * Actually function searches for line within internal buffer. If line is not
+ * found then function reads new data from file and searches for the line again.
+ * The last line in file (without trailing EOL) is considered as line too.
+ *
+ * @warning Returned pointer must be freed by faux_str_free() later.
+ *
+ * @param [in] f File object.
+ * @return Line pointer or NULL on error.
+ */
 char *faux_file_getline(faux_file_t *f) {
 
 	ssize_t bytes_readed = 0;
@@ -241,6 +330,17 @@ char *faux_file_getline(faux_file_t *f) {
 }
 
 
+/** @brief Writes data to file.
+ *
+ * The system write() can be interrupted by signal or can write less bytes
+ * than specified. This function will continue to write data until all data
+ * will be written or error occured.
+ *
+ * @param [in] f File object.
+ * @param [in] buf Buffer to write.
+ * @param [in] n Number of bytes to write.
+ * @return Number of bytes written or NULL on error.
+ */
 ssize_t faux_file_write(faux_file_t *f, const void *buf, size_t n) {
 
 	ssize_t bytes_written = 0;