Changeset a18c1d9f1125780022a9b17c893e4a7349a1483f

Show
Ignore:
Timestamp:
05/03/08 23:02:44 (4 months ago)
Author:
Rémi Denis-Courmont <rem@videolan.org>
git-committer:
Rémi Denis-Courmont <rem@videolan.org> 1209848564 +0300
git-parent:

[4724e090bc4e2663553d39709a8e8e2e59d7a85e]

git-author:
Rémi Denis-Courmont <rem@videolan.org> 1209848564 +0300
Message:

Improve doxy comments

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • src/text/unicode.c

    r0fd1b74 ra18c1d9  
    178178} 
    179179 
    180  
     180/** 
     181 * Releases (if needed) a localized or uniformized string. 
     182 * @param str non-NULL return value from FromLocale() or ToLocale(). 
     183 */ 
    181184void LocaleFree (const char *str) 
    182185{ 
    …… 
    193196 
    194197/** 
    195  * FromLocale: converts a locale string to UTF-8 
    196  * 
    197  * @param locale nul-terminated string to be converted 
     198 * Converts a string from the system locale character encoding to UTF-8. 
     199 * 
     200 * @param locale nul-terminated string to convert 
    198201 * 
    199202 * @return a nul-terminated UTF-8 string, or NULL in case of error. 
    …… 
    206209} 
    207210 
     211/** 
     212 * converts a string from the system locale character encoding to utf-8, 
     213 * the result is always allocated on the heap. 
     214 * 
     215 * @param locale nul-terminated string to convert 
     216 * 
     217 * @return a nul-terminated utf-8 string, or null in case of error. 
     218 * The result must be freed using free() - as with the strdup() function. 
     219 */ 
    208220char *FromLocaleDup (const char *locale) 
    209221{ 
    …… 
    213225 
    214226/** 
    215  * ToLocale: converts a UTF-8 string to local system encoding. 
     227 * ToLocale: converts an UTF-8 string to local system encoding. 
    216228 * 
    217229 * @param utf8 nul-terminated string to be converted 
    …… 
    227239 
    228240 
     241/** 
     242 * converts a string from UTF-8 to the system locale character encoding, 
     243 * the result is always allocated on the heap. 
     244 * 
     245 * @param utf8 nul-terminated string to convert 
     246 * 
     247 * @return a nul-terminated string, or null in case of error. 
     248 * The result must be freed using free() - as with the strdup() function. 
     249 */ 
    229250char *ToLocaleDup (const char *utf8) 
    230251{ 
    …… 
    234255 
    235256/** 
    236  * utf8_open: open() wrapper for UTF-8 filenames 
     257 * Opens a system file handle using UTF-8 paths. 
     258 * 
     259 * @param filename file path to open (with UTF-8 encoding) 
     260 * @param flags open() flags, see the C library open() documentation 
     261 * @param mode file permissions if creating a new file 
     262 * @return a file handle on success, -1 on error (see errno). 
    237263 */ 
    238264int utf8_open (const char *filename, int flags, mode_t mode) 
    …… 
    272298 
    273299/** 
    274  * utf8_fopen: fopen() wrapper for UTF-8 filenames 
     300 * Opens a FILE pointer using UTF-8 filenames. 
     301 * @param filename file path, using UTF-8 encoding 
     302 * @param mode fopen file open mode 
     303 * @return NULL on error, an open FILE pointer on success. 
    275304 */ 
    276305FILE *utf8_fopen (const char *filename, const char *mode) 
    …… 
    328357 
    329358/** 
    330  * utf8_mkdir: Calls mkdir() after conversion of file name to OS locale 
     359 * Creates a directory using UTF-8 paths. 
    331360 * 
    332361 * @param dirname a UTF-8 string with the name of the directory that you 
    333362 *        want to create. 
    334  * @return A 0 return value indicates success. A -1 return value indicates an 
    335  *        error, and an error code is stored in errno 
     363 * @param mode directory permissions 
     364 * @return 0 on success, -1 on error (see errno). 
    336365 */ 
    337366int utf8_mkdir( const char *dirname, mode_t mode ) 
    …… 
    392421 
    393422/** 
    394  * utf8_opendir: wrapper that converts dirname to the locale in use by the OS 
     423 * Opens a DIR pointer using UTF-8 paths 
    395424 * 
    396425 * @param dirname UTF-8 representation of the directory name 
    397  * 
    398  * @return a pointer to the DIR struct. Release with closedir(). 
     426 * @return a pointer to the DIR struct, or NULL in case of error. 
     427 * Release with standard closedir(). 
    399428 */ 
    400429DIR *utf8_opendir( const char *dirname ) 
    …… 
    424453 
    425454/** 
    426  * utf8_readdir: a readdir wrapper that returns the name of the next entry 
    427  *     in the directory as a UTF-8 string. 
     455 * Reads the next file name from an open directory. 
    428456 * 
    429457 * @param dir The directory that is being read 
    430458 * 
    431  * @return a UTF-8 string of the directory entry. Use free() to free this memory. 
     459 * @return a UTF-8 string of the directory entry. 
     460 * Use free() to free this memory. 
    432461 */ 
    433462char *utf8_readdir( DIR *dir ) 
    …… 
    456485} 
    457486 
     487/** 
     488 * Does the same as utf8_scandir(), but takes an open directory pointer 
     489 * instead of a directory path. 
     490 */ 
    458491int utf8_loaddir( DIR *dir, char ***namelist, 
    459492                  int (*select)( const char * ), 
    …… 
    512545} 
    513546 
     547/** 
     548 * Selects file entries from a directory, as GNU C scandir(), yet using 
     549 * UTF-8 file names. 
     550 * 
     551 * @param dirname UTF-8 diretory path 
     552 * @param pointer [OUT] pointer set, on succesful completion, to the address 
     553 * of a table of UTF-8 filenames. All filenames must be freed with free(). 
     554 * The table itself must be freed with free() as well. 
     555 * 
     556 * @return How many file names were selected (possibly 0), 
     557 * or -1 in case of error. 
     558 */ 
    514559int utf8_scandir( const char *dirname, char ***namelist, 
    515560                  int (*select)( const char * ), 
    …… 
    562607} 
    563608 
    564  
     609/** 
     610 * Finds file/inode informations, as stat(). 
     611 * Consider usign fstat() instead, if possible. 
     612 * 
     613 * @param filename UTF-8 file path 
     614 */ 
    565615int utf8_stat( const char *filename, struct stat *buf) 
    566616{ 
    …… 
    568618} 
    569619 
     620/** 
     621 * Finds file/inode informations, as lstat(). 
     622 * Consider usign fstat() instead, if possible. 
     623 * 
     624 * @param filename UTF-8 file path 
     625 */ 
    570626int utf8_lstat( const char *filename, struct stat *buf) 
    571627{ 
    …… 
    574630 
    575631/** 
    576  * utf8_unlink: Calls unlink() after conversion of file name to OS locale 
     632 * Removes a file. 
    577633 * 
    578634 * @param filename a UTF-8 string with the name of the file you want to delete. 
    …… 
    618674 
    619675/** 
    620  * utf8_*printf: *printf with conversion from UTF-8 to local encoding 
     676 * Formats an UTF-8 string as vasprintf(), then print it to stdout, with 
     677 * appropriate conversion to local encoding. 
    621678 */ 
    622679static int utf8_vasprintf( char **str, const char *fmt, va_list ap ) 
    …… 
    632689} 
    633690 
     691/** 
     692 * Formats an UTF-8 string as vfprintf(), then print it, with 
     693 * appropriate conversion to local encoding. 
     694 */ 
    634695int utf8_vfprintf( FILE *stream, const char *fmt, va_list ap ) 
    635696{ 
    …… 
    644705} 
    645706 
     707/** 
     708 * Formats an UTF-8 string as fprintf(), then print it, with 
     709 * appropriate conversion to local encoding. 
     710 */ 
    646711int utf8_fprintf( FILE *stream, const char *fmt, ... ) 
    647712{ 
    …… 
    721786 
    722787/** 
    723  * EnsureUTF8: replaces invalid/overlong UTF-8 sequences with question marks 
     788 * Replaces invalid/overlong UTF-8 sequences with question marks. 
    724789 * Note that it is not possible to convert from Latin-1 to UTF-8 on the fly, 
    725790 * so we don't try that, even though it would be less disruptive. 
    …… 
    734799 
    735800/** 
    736  * IsUTF8: checks whether a string is a valid UTF-8 byte sequence. 
     801 * Checks whether a string is a valid UTF-8 byte sequence. 
    737802 * 
    738803 * @param str nul-terminated string to be checked