# HG changeset patch
# User rosfran
# Date 1174425838 0
# Node ID c1601c03cc7821c7123aab67d87f3dbfb688b145
# Parent  18916d01fd457a30f2b48e36225265cecc44324b
[svn r425] Added internal DOxygen documentation.

diff -r 18916d01fd45 -r c1601c03cc78 gmyth/src/gmyth_backendinfo.c
--- a/gmyth/src/gmyth_backendinfo.c	Tue Mar 20 15:08:35 2007 +0000
+++ b/gmyth/src/gmyth_backendinfo.c	Tue Mar 20 21:23:58 2007 +0000
@@ -1,11 +1,14 @@
-
 /**
  * GMyth Library
  *
  * @file gmyth/gmyth_backend_info.c
  * 
+ * @brief <p> This component represents all the MythTV backend server
+ * 						configuration information.
+ *
  * Copyright (C) 2006 INdT - Instituto Nokia de Tecnologia.
  * @author Hallyson Melo <hallyson.melo@indt.org.br>
+ * @author Rosfran Borges <rosfran.borges@indt.org.br>
  *
  *//*
  * 
diff -r 18916d01fd45 -r c1601c03cc78 gmyth/src/gmyth_backendinfo.h
--- a/gmyth/src/gmyth_backendinfo.h	Tue Mar 20 15:08:35 2007 +0000
+++ b/gmyth/src/gmyth_backendinfo.h	Tue Mar 20 21:23:58 2007 +0000
@@ -3,9 +3,12 @@
  *
  * @file gmyth/gmyth_backend_info.h
  * 
+ * @brief <p> This component represents all the MythTV backend server
+ * 						configuration information.
  *
  * Copyright (C) 2006 INdT - Instituto Nokia de Tecnologia.
  * @author Hallyson Melo <hallyson.melo@indt.org.br>
+ * @author Rosfran Borges <rosfran.borges@indt.org.br>
  *
  *//*
  * 
diff -r 18916d01fd45 -r c1601c03cc78 gmyth/src/gmyth_common.c
--- a/gmyth/src/gmyth_common.c	Tue Mar 20 15:08:35 2007 +0000
+++ b/gmyth/src/gmyth_common.c	Tue Mar 20 21:23:58 2007 +0000
@@ -7,6 +7,7 @@
  *
  * Copyright (C) 2006 INdT - Instituto Nokia de Tecnologia.
  * @author Leonardo Sobral Cunha <leonardo.cunha@indt.org.br>
+ * @author Rosfran Borges <rosfran.borges@indt.org.br>
  *
  *//*
  * 
@@ -110,7 +111,7 @@
 static void 
 free_channel_data (gpointer data, gpointer user_data)
 {
-    // Frees the GMythChannelInfo structure
+    /* Frees the GMythChannelInfo structure */
     g_free(data);
 }
 
diff -r 18916d01fd45 -r c1601c03cc78 gmyth/src/gmyth_common.h
--- a/gmyth/src/gmyth_common.h	Tue Mar 20 15:08:35 2007 +0000
+++ b/gmyth/src/gmyth_common.h	Tue Mar 20 21:23:58 2007 +0000
@@ -7,6 +7,7 @@
  *
  * Copyright (C) 2006 INdT - Instituto Nokia de Tecnologia.
  * @author Leonardo Sobral Cunha <leonardo.cunha@indt.org.br>
+ * @author Rosfran Borges <rosfran.borges@indt.org.br>
  *
  *//*
  * 
diff -r 18916d01fd45 -r c1601c03cc78 gmyth/src/gmyth_file_transfer.c
--- a/gmyth/src/gmyth_file_transfer.c	Tue Mar 20 15:08:35 2007 +0000
+++ b/gmyth/src/gmyth_file_transfer.c	Tue Mar 20 21:23:58 2007 +0000
@@ -225,7 +225,10 @@
 }
 
 /** 
- * Creates a new instance of GMyth File Transfer.
+ * Creates a new instance of GMythFileTransfer.
+ * 
+ * @param backend_info The BackendInfo instance, with all the MythTV network 
+ * 										 configuration data.
  * 
  * @return a new instance of the File Transfer. 
  */
@@ -240,6 +243,13 @@
   return transfer;
 }
 
+/** 
+ * Creates a new instance of GMythFileTransfer.
+ * 
+ * @param uri_str The URI poiting to the MythTV backend server.
+ * 
+ * @return a new instance of the File Transfer. 
+ */
 GMythFileTransfer* 
 gmyth_file_transfer_new_with_uri (const gchar* uri_str)
 {
@@ -250,6 +260,14 @@
   return transfer;
 }
 
+/** 
+ * Open a File Transfer connection in order to get a remote file.
+ * 
+ * @param transfer The actual File Transfer instance. 
+ * @param filename The file name of the remote file to be transfered to the client.
+ * 
+ * @return <code>true</code>, if the connection opening had been done successfully. 
+ */
 gboolean
 gmyth_file_transfer_open (GMythFileTransfer *transfer, const gchar* filename)
 {
@@ -285,6 +303,13 @@
 
 }
 
+/** 
+ * Connect a File Transfer binary client socket to a remote file.
+ * 
+ * @param transfer The actual File Transfer instance. 
+ * 
+ * @return <code>true</code>, if the connection had been configured successfully. 
+ */
 static gboolean
 gmyth_connect_to_backend (GMythFileTransfer *transfer)
 {
@@ -385,6 +410,14 @@
   return ret;
 }    
 
+/** 
+ * Receives a GObject signal coming from a LiveTV instance, all the time a 
+ * program info changes.
+ * 
+ * @param transfer The actual File Transfer instance. 
+ * @param msg_code The MythTV backend message status code.
+ * @param live_tv A pointer to the LiveTV instance. * 
+ */
 void
 gmyth_file_transfer_emit_program_info_changed_signal ( GMythFileTransfer *transfer, gint msg_code,
 			gpointer live_tv ) 
@@ -404,6 +437,13 @@
 
 }
 
+/** 
+ * Checks if the actual File Transfer connection is open.
+ * 
+ * @param transfer The actual File Transfer instance. 
+ * 
+ * @return <code>true</code>, if the File Transfer connection is opened. 
+ */
 gboolean
 gmyth_file_transfer_is_open (GMythFileTransfer *transfer)
 {
@@ -433,6 +473,11 @@
     return ( strlist != NULL && gmyth_string_list_get_int( strlist, 0 ) == 1 );
 }
 
+/** 
+ * Closes a remote File Transfer connection.
+ * 
+ * @param transfer The actual File Transfer instance. 
+ */
 void
 gmyth_file_transfer_close( GMythFileTransfer *transfer )
 {
@@ -472,6 +517,15 @@
 
 }
 
+/** 
+ * Do a seek operation (moves the read/write file pointer) on a remote file.
+ * 
+ * @param transfer The actual File Transfer instance. 
+ * @param pos The position to be moved in the remote file.
+ * @param whence Tells to what direction seek movement should be done.
+ * 
+ * @return The actual position on the remote file (after seek has been done). 
+ */
 gint64
 gmyth_file_transfer_seek(GMythFileTransfer *transfer, guint64 pos, gint whence)
 {
@@ -510,6 +564,14 @@
   return retval;
 }
 
+/** 
+ * Acquire access to a remote file socket read/write pointer.
+ * 
+ * @param transfer The actual File Transfer instance.
+ * @param do_wait Waits or not on a GCond, when trying to read from the remote socket.
+ * 
+ * @return <code>true</code>, if the acquire had been got. 
+ */
 static gboolean 
 myth_control_acquire_context( GMythFileTransfer *transfer, gboolean do_wait )
 {
@@ -538,6 +600,13 @@
   return ret;
 }
 
+/** 
+ * Release access to a remote file socket read/write pointer.
+ * 
+ * @param transfer The actual File Transfer instance.
+ * 
+ * @return <code>true</code>, if the socket read/write permissions had been releaseds. 
+ */
 static gboolean 
 myth_control_release_context( GMythFileTransfer *transfer ) 
 {
@@ -558,6 +627,19 @@
   return ret;
 }
 
+/** 
+ * Reads a block from a remote file.
+ * 
+ * @param transfer The actual File Transfer instance.
+ * @param data A GByteArray instance, where all the binary data representing 
+ * 						 the remote file will be stored.
+ * @param size The block size, in bytes, to be requested from a remote file.
+ * @param read_unlimited Tells the backend to read indefinitely (LiveTV), or only 
+ * 											 gets the actual size
+ * 
+ * @return The actual block size (in bytes) returned by REQUEST_BLOCK message,
+ * 				or the error code. 
+ */
 gint 
 gmyth_file_transfer_read(GMythFileTransfer *transfer, GByteArray *data, gint size, gboolean read_unlimited)
 {
@@ -574,7 +656,7 @@
   GIOCondition io_cond_control;
   GIOStatus io_status = G_IO_STATUS_NORMAL, io_status_control = G_IO_STATUS_NORMAL;
   
-  gboolean ret = TRUE;   
+  gboolean ret = TRUE;
 
   GString *query;
   
@@ -712,6 +794,7 @@
   return total_read;
 }
 
+
 static void 
 gmyth_file_transfer_program_info_changed( GMythFileTransfer *transfer, 
 										gint msg_code, gpointer livetv_transfer )
@@ -733,6 +816,15 @@
 	
 }
 
+/** 
+ * Sets the timeout flag of a file being transfered.
+ * 
+ * @param transfer The actual File Transfer instance.
+ * @param fast If this is <code>true</code>, sets the remote timeout to be as fast
+ * 						as possible.
+ * 
+ * @return <code>true</code>, if the acquire had been got. 
+ */
 gboolean 
 gmyth_file_transfer_settimeout( GMythFileTransfer *transfer, gboolean fast )
 {
@@ -765,6 +857,13 @@
   return TRUE;
 }
 
+/** 
+ * Gets the actual file size of the binary content.
+ * 
+ * @param transfer The actual File Transfer instance.
+ * 
+ * @return The actual file size in bytes. 
+ */
 guint64
 gmyth_file_transfer_get_filesize (GMythFileTransfer *transfer)
 {
diff -r 18916d01fd45 -r c1601c03cc78 gmyth/src/gmyth_programinfo.c
--- a/gmyth/src/gmyth_programinfo.c	Tue Mar 20 15:08:35 2007 +0000
+++ b/gmyth/src/gmyth_programinfo.c	Tue Mar 20 21:23:58 2007 +0000
@@ -3,10 +3,11 @@
  *
  * @file gmyth/gmyth_programinfo.c
  * 
- * @brief <p> GMythFileTransfer deals with the file streaming media remote/local
- * transfering to the MythTV frontend.
+ * @brief <p> GMythProgramInfo representing the program info, with the
+ * configuration data to the actual remote file in the TV chain.
  *
  * Copyright (C) 2006 INdT - Instituto Nokia de Tecnologia.
+ * @author Rosfran Borges <rosfran.borges@indt.org.br>
  * @author Leonardo Sobral Cunha <leonardo.cunha@indt.org.br>
  *
  *//*
@@ -251,6 +252,16 @@
     return program_info;
 }
 
+/**
+ * Converts an instance of a GMythProgramInfo, to a GMythStringList.
+ * 
+ * @param prog A GMythProgramInfo instance.
+ * @param slist The GMythStringList to be passed to this function, in order to
+ * 							give the responsibility of the string list creation to the
+ * 						  API user.
+ * 
+ * @return a GMythStringList with the program info fields.
+ */
 GMythStringList*
 gmyth_program_info_to_string_list (GMythProgramInfo *prog, GMythStringList *slist)
 {
@@ -319,6 +330,13 @@
     return slist;
 }
 
+/**
+ * Converts an instance of a GMythStringList, to a GMythProgramInfo.
+ * 
+ * @param slist The GMythStringList got from the MythTV backend server.
+ * 
+ * @return a GMythProgramInfo representing the string list got from network.
+ */
 GMythProgramInfo*
 gmyth_program_info_from_string_list ( GMythStringList *slist )
 {
@@ -397,6 +415,13 @@
 	return ( str != NULL && str->str != NULL && strlen( str->str ) > 0 ? str->str : " " );
 }
 
+/**
+ * Prints out an instance of a GMythProgramInfo.
+ * 
+ * @param prog A GMythProgramInfo instance.
+ * 
+ * @return a string representing the program info.
+ */
 const gchar*
 gmyth_program_info_to_string( const GMythProgramInfo* prog )
 {
diff -r 18916d01fd45 -r c1601c03cc78 gmyth/src/gmyth_programinfo.h
--- a/gmyth/src/gmyth_programinfo.h	Tue Mar 20 15:08:35 2007 +0000
+++ b/gmyth/src/gmyth_programinfo.h	Tue Mar 20 21:23:58 2007 +0000
@@ -1,11 +1,13 @@
 /**
  * GMyth Library
+ *
+ * @file gmyth/gmyth_programinfo.h
  * 
- * @file gmyth/gmyth_common.h
- * 
- * @brief <p> This file contains basic common functions for the gmyth library.
+ * @brief <p> GMythProgramInfo representing the program info, with the
+ * configuration data to the actual remote file in the TV chain.
  *
  * Copyright (C) 2006 INdT - Instituto Nokia de Tecnologia.
+ * @author Rosfran Borges <rosfran.borges@indt.org.br>
  * @author Leonardo Sobral Cunha <leonardo.cunha@indt.org.br>
  *
  *//*
@@ -23,6 +25,7 @@
  * You should have received a copy of the GNU Lesser General Public License
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ *
  */
 
 #ifndef _GMYTH_PROGRAMINFO_H
diff -r 18916d01fd45 -r c1601c03cc78 gmyth/src/gmyth_recorder.c
--- a/gmyth/src/gmyth_recorder.c	Tue Mar 20 15:08:35 2007 +0000
+++ b/gmyth/src/gmyth_recorder.c	Tue Mar 20 21:23:58 2007 +0000
@@ -1,14 +1,15 @@
 /**
  * GMyth Library
  *
- * @file gmyth/gmyth_remote_encoder.c
+ * @file gmyth/gmyth_recorder.c
  * 
- * @brief <p> GMythRecorder class defines functions for playing live tv.
+ * @brief <p> GMythRecorder defines functions for playing live tv.
  *
  * The remote encoder is used by gmyth_tvplayer to setup livetv. 
  *
  * Copyright (C) 2006 INdT - Instituto Nokia de Tecnologia.
  * @author Hallyson Luiz de Morais Melo <hallyson.melo@indt.org.br>
+ * @author Rosfran Borges <rosfran.borges@indt.org.br>
  *
  *//*
  * 
@@ -115,6 +116,7 @@
 /** Configures the remote encoder instance connecting it to Mythtv backend.
  * 
  * @param recorder the GMythRecorder instance.
+ * 
  * @return TRUE if successfull, FALSE if any error happens.
  */
 gboolean
@@ -754,6 +756,13 @@
 
 }
 
+/**
+ * Requests the actual remote file position on a LiveTV instance.
+ * 
+ * @param recorder The GMythRecorder instance.
+ * 
+ * @return The position, in bytes, of the offset to the read header.
+ */
 gint64
 gmyth_recorder_get_file_position ( GMythRecorder *recorder )
 {
@@ -786,6 +795,13 @@
 
 }
 
+/**
+ * Asks MythTV backend server about if it started to record the remote file.
+ * 
+ * @param recorder The GMythRecorder instance.
+ * 
+ * @return <code>true</code>, if the actual remote file is bein recorded.
+ */
 gboolean
 gmyth_recorder_is_recording ( GMythRecorder *recorder )
 {
@@ -824,6 +840,13 @@
 
 }
 
+/**
+ * Finish remote file recording process.
+ * 
+ * @param recorder The GMythRecorder instance.
+ * 
+ * @return <code>true</code>, if the recording had been actually closed.
+ */
 gboolean
 gmyth_recorder_finish_recording ( GMythRecorder *recorder )
 {
diff -r 18916d01fd45 -r c1601c03cc78 gmyth/src/gmyth_recorder.h
--- a/gmyth/src/gmyth_recorder.h	Tue Mar 20 15:08:35 2007 +0000
+++ b/gmyth/src/gmyth_recorder.h	Tue Mar 20 21:23:58 2007 +0000
@@ -3,10 +3,13 @@
  *
  * @file gmyth/gmyth_recorder.h
  * 
- * @brief <p> GMythRecorder class defines functions for playing live tv.
+ * @brief <p> GMythRecorder defines functions for playing live tv.
+ *
+ * The remote encoder is used by gmyth_tvplayer to setup livetv. 
  *
  * Copyright (C) 2006 INdT - Instituto Nokia de Tecnologia.
  * @author Hallyson Luiz de Morais Melo <hallyson.melo@indt.org.br>
+ * @author Rosfran Borges <rosfran.borges@indt.org.br>
  *
  *//*
  * 
diff -r 18916d01fd45 -r c1601c03cc78 gmyth/src/gmyth_remote_util.c
--- a/gmyth/src/gmyth_remote_util.c	Tue Mar 20 15:08:35 2007 +0000
+++ b/gmyth/src/gmyth_remote_util.c	Tue Mar 20 21:23:58 2007 +0000
@@ -7,6 +7,7 @@
  *
  * Copyright (C) 2006 INdT - Instituto Nokia de Tecnologia.
  * @author Hallyson Luiz de Morais Melo <hallyson.melo@indt.org.br>
+ * @author Rosfran Borges <rosfran.borges@indt.org.br>
  *
  *//*
  * 
@@ -35,10 +36,12 @@
 #include "gmyth_stringlist.h"
 #include "gmyth_debug.h"
 
-/** Requests the Mythtv backend for a free remote recorder.
+/** 
+ * Requests the Mythtv backend for a free remote recorder.
  * 
  * @param socket The socket instance where to send the command.
  * @param curr The recorder index, or -1 to consider the first one.
+ * 
  * @return the remote encoder instance available, or NULL if any error happens.
  */
 GMythRecorder*
@@ -83,6 +86,7 @@
  * Requests the Mythtv backend for the number of free remote recorders.
  * 
  * @param socket The socket instance where to send the command.
+ * 
  * @return the number of remote encoders instance available, or 0 if no one is actually free..
  */
 gint
diff -r 18916d01fd45 -r c1601c03cc78 gmyth/src/gmyth_uri.c
--- a/gmyth/src/gmyth_uri.c	Tue Mar 20 15:08:35 2007 +0000
+++ b/gmyth/src/gmyth_uri.c	Tue Mar 20 21:23:58 2007 +0000
@@ -125,7 +125,8 @@
 	G_OBJECT_CLASS (gmyth_uri_parent_class)->finalize (object);
 }
 
-/** Creates a new instance of GMythURI.
+/** 
+ * Creates a new instance of GMythURI.
  * 
  * @return a new instance of GMythURI.
  */
@@ -137,7 +138,10 @@
     return gmyth_uri;
 }
 
-/** Creates a new instance of GMythURI.
+/** 
+ * Creates a new instance of GMythURI.
+ * 
+ * @param uri_str The URI string representing this URI instance.
  * 
  * @return a new instance of GMythURI.
  */
@@ -151,6 +155,15 @@
     return gmyth_uri;
 }
 
+/** 
+ * Gets the starting offset of a substring inside a given string.
+ * 
+ * @param haystack The given string to be searched for patterns.
+ * @param needle The substring that should be matched over the haystack.
+ * 
+ * @return The starting offset to the given substring, or <code>-1</code> if the
+ * 				 haystack function parameter doesn't contains the needle string argument.
+ */
 static gint 
 gmyth_strstr (const gchar *haystack, const gchar *needle)
 {
@@ -167,6 +180,13 @@
 
 }
 
+/** 
+ * Checks if a URI is absolute.
+ * 
+ * @param uri The GMythURI instance.
+ * 
+ * @return <code>true</code>, if the URI is absolute.
+ */
 static gboolean
 gmyth_uri_isabsolute (const GMythURI *uri)
 {
@@ -180,6 +200,19 @@
 	return ret;	
 }
 
+/** 
+ * Searches for the first reverse character occurrence, from a given 
+ * list of characters, inside a given string.
+ * 
+ * @param str The given string to be searched for characters occurrence.
+ * @param chars The characters list. If this string returns 4 on strlen, there are
+ * 						  four possible characters to be matched.
+ * @param nchars The number of characters to be matched, which has at most 
+ * 							 strlen(chars).
+ * 
+ * @return The starting offset to the first character occurrence, 
+ *         or <code>-1</code> if the no character of the list could be found.
+ */
 static gint
 gmyth_strrchr( const gchar *str, const gchar *chars, const gint nchars )
 {
@@ -211,6 +244,13 @@
 		return "";		
 }
 
+/** 
+ * Parses a URI string into a GMythURI instance.
+ * 
+ * @param uri The GMythURI instance.
+ * @param value The URI string to be parsed.
+ *
+ */
 static void
 gmyth_uri_parser_setup_and_new( GMythURI *uri, const gchar *value )
 {
@@ -364,6 +404,13 @@
 	
 }
 
+/** 
+ * Gets the channel name fro a URI instance.
+ * 
+ * @param uri The GMythURI instance.
+ * 
+ * @return The channel name, got from the substring "?channel=[channel_name]".
+ */
 gchar*
 gmyth_uri_get_channel_name( GMythURI* uri )
 {
diff -r 18916d01fd45 -r c1601c03cc78 gmyth/src/gmyth_util.c
--- a/gmyth/src/gmyth_util.c	Tue Mar 20 15:08:35 2007 +0000
+++ b/gmyth/src/gmyth_util.c	Tue Mar 20 21:23:58 2007 +0000
@@ -1,29 +1,31 @@
 /**
-* GMyth Library
-*
-* @file gmyth/gmyth_util.c
-* 
-* @brief <p> This component provides utility functions.
-* 
-* Copyright (C) 2006 INdT - Instituto Nokia de Tecnologia.
-* @author Hallyson Luiz de Morais Melo <hallyson.melo@indt.org.br>
-*
-*//*
-* 
-* This program is free software; you can redistribute it and/or modify
-* it under the terms of the GNU Lesser General Public License as published by
-* the Free Software Foundation; either version 2 of the License, or
-* (at your option) any later version.
-*
-* This program is distributed in the hope that it will be useful,
-* but WITHOUT ANY WARRANTY; without even the implied warranty of
-* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-* GNU General Public License for more details.
-*
-* You should have received a copy of the GNU Lesser General Public License
-* along with this program; if not, write to the Free Software
-* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
-*/
+ * GMyth Library
+ *
+ * @file gmyth/gmyth_util.c
+ * 
+ * @brief <p> This component provides utility functions 
+ * 	(dealing with dates, time, string formatting, etc.).
+ * 
+ * Copyright (C) 2006 INdT - Instituto Nokia de Tecnologia.
+ * @author Hallyson Luiz de Morais Melo <hallyson.melo@indt.org.br>
+ * @author Rosfran Borges <rosfran.borges@indt.org.br>
+ *
+ *//*
+ * 
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ */
  
 #ifdef HAVE_CONFIG_H
 #include "config.h"
@@ -394,11 +396,13 @@
 	return time;
 }
 
-/** Decodes a long long variable from the string list
+/** 
+ * Decodes a long long variable from the string list
  * format of the myhtprotocol.
  * 
  * @param strlist the string list of mythprotocol values
  * @param offset  the list node offset of the long long variable
+ * 
  * @return gint64  the long long converted value
  */
 gint64
@@ -424,6 +428,14 @@
 
 }
 
+/** 
+ * Checks if the given remote file exists.
+ * 
+ * @param backend_info The GMythBackendInfo instance.
+ * @param filename The file name of the remote file.
+ * 
+ * @return <code>true</code>, if the remote file exists.
+ */
 gboolean
 gmyth_util_file_exists (GMythBackendInfo *backend_info, const gchar* filename)
 {
@@ -464,6 +476,15 @@
     return res;    
 }
 
+/** 
+ * Checks if the given remote file exists, and gets its remote directory.
+ * 
+ * @param backend_info The GMythBackendInfo instance.
+ * @param filename The file name of the remote file.
+ * @param current_dir String pointer to the directory where the remote file is stored.
+ * 
+ * @return <code>true</code>, if the remote file exists.
+ */
 gboolean
 gmyth_util_file_exists_and_get_remote_dir (GMythBackendInfo *backend_info, 
 						const gchar* filename, gchar** current_dir)
@@ -511,6 +532,15 @@
     return res;    
 }
 
+/** 
+ * Creates a file name to a possible existing remote file,
+ * based on some fields of the LiveTV/recorded program info.
+ * 
+ * @param chan_id The channel ID number.
+ * @param start_time The start time of the recording.
+ * 
+ * @return The string representing the file name.
+ */
 gchar*
 gmyth_util_create_filename( const gint chan_id, const GTimeVal* start_time )
 { 
diff -r 18916d01fd45 -r c1601c03cc78 gmyth/src/gmyth_util.h
--- a/gmyth/src/gmyth_util.h	Tue Mar 20 15:08:35 2007 +0000
+++ b/gmyth/src/gmyth_util.h	Tue Mar 20 21:23:58 2007 +0000
@@ -1,29 +1,31 @@
 /**
-* GMyth Library
-*
-* @file gmyth/gmyth_util.h
-* 
-* @brief <p> This component provides utility functions.
-* 
-* Copyright (C) 2006 INdT - Instituto Nokia de Tecnologia.
-* @author Hallyson Luiz de Morais Melo <hallyson.melo@indt.org.br>
-*
-*//*
-* 
-* This program is free software; you can redistribute it and/or modify
-* it under the terms of the GNU Lesser General Public License as published by
-* the Free Software Foundation; either version 2 of the License, or
-* (at your option) any later version.
-*
-* This program is distributed in the hope that it will be useful,
-* but WITHOUT ANY WARRANTY; without even the implied warranty of
-* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-* GNU General Public License for more details.
-*
-* You should have received a copy of the GNU Lesser General Public License
-* along with this program; if not, write to the Free Software
-* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
-*/
+ * GMyth Library
+ *
+ * @file gmyth/gmyth_util.h
+ * 
+ * @brief <p> This component provides utility functions 
+ * 	(dealing with dates, time, string formatting, etc.).
+ * 
+ * Copyright (C) 2006 INdT - Instituto Nokia de Tecnologia.
+ * @author Hallyson Luiz de Morais Melo <hallyson.melo@indt.org.br>
+ * @author Rosfran Borges <rosfran.borges@indt.org.br>
+ *
+ *//*
+ * 
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ */
 
 #ifndef GMYTH_UTIL_H_
 #define GMYTH_UTIL_H_