| Re: [AD] Proposed documentation for packfile functions |
[ Thread Index |
Date Index
| More lists.liballeg.org/allegro-developers Archives
]
+@@int @pack_fclose(PACKFILE *f);
+@xref pack_fopen_chunk, packfile_password
+ Closes a PACKFILE stream previously opened with pack_fopen_chunk. After
Closes the stream f previously...
Why pack_fopen_chunk? Pasto?
+ you have closed the stream, performing operations on it will yield errors
+ in your application making it crash or even block your OS.
...application (e.g. crash it) or even block your OS.
+@retval
+ Returns zero on success. On error it returns an error code which is
On error, returns...
+ also stored in errno. This function can fail only when writting to files:
...writing...
+ if the file was opened in read mode it will always succeed.
Missing comma before "it".
+@@int @pack_fseek(PACKFILE *f, int offset);
+@xref pack_fopen, pack_fopen_chunk
+ With fseek you can move the file position of the PACKFILE stream. Unlike
Moves the position indicator of the stream f.
+ the `fseek' function, seeking only supports forward movement relative to
... the standard 'fseek' function, this supports only forward movements...
+ the current position and in read only streams, so don't use negative
... read-only...
+@retval
+ Returns zero on success, otherwise negative, storing the underlaying OS
... or a negative number on error, storing
+ error code in allegro_errno (if there was any).
the error code in errno.
---- cut here ---
allegro_errno is not meant to be accessed by the user. He must use the
regular errno variable. allegro_errno is only an (intended to be internal
but necessarily exported) bridge between errno and Allegro.
---- cut here ---
+@@int @pack_ferror(PACKFILE *f);
+@xref pack_fopen, pack_fopen_chunk
+ Since EOF is used to report both end of file and random errors, it's
...errors by some fuctions, it's
+ better to use the pack_feof function to check explicitly for end of file
+ and pack_ferror to check for errors. Both functions check indicators that
+ are part of the internal state of the PACKFILE stream to detect correctly
+ the different situations.
+@retval
+ Returns nonzero if the error indicator for the PACKFILE stream is set,
+ indicating that an error has occurred on a previous operation of the
...occured during a ... on the
+ stream.
---- cut here ---
I think the first part should appear after the description of the function,
which happens to be reduced to the description of its return value since the
function has no side-effects.
---- cut here ---
+@@int @pack_getc(PACKFILE *f);
+@xref pack_fopen, pack_fopen_chunk
+ Reads and returns the next character from the stream, or EOF if the end
I think "Reads" is superfluous here.
+@@int @pack_putc(int c, PACKFILE *f);
+@xref pack_fopen, pack_fopen_chunk
+ Puts a character in the stream.
+@retval
+ Returns EOF if there were any problems, zero otherwise.
Returns zero on success, or EOF on error.
---- cut here ---
I think we ought to try to standardize as much as possible.
---- cut here ---
+@@int @pack_igetw(PACKFILE *f);
+@xref pack_getc
+ Like pack_getc, but reads a 16 bit word from a file, using Intel byte
... 16-bit word...
+ ordering (least significat byte first, little-endian).
(least significat byte first, a.k.a little-endian).
Same for the 3 others.
+@@int @pack_mgetw(PACKFILE *f);
+@xref pack_getc
+ Like pack_getc, but reads a 16 bit word from a file, using Motorola byte
... 16-bit word ...
+ ordering (most significant byte first, big-endian).
(most significant byte first, a.k.a big-endian).
Same for the 3 others.
+@@long @pack_fread(void *p, long n, PACKFILE *f);
+@xref pack_fopen, pack_fopen_chunk, pack_feof
+ Reads n bytes from the PACKFILE stream f, storing them at the memory
... from the stream f...
+ location p.
location pointed to by p.
+@retval
+ Returns the number of items read, which will be less than n if EOF is
... number of bytes read ...
+@@long @pack_fwrite(const void *p, long n, PACKFILE *f);
+@xref pack_fopen, pack_fopen_chunk, pack_feof
+ Writes n bytes to the PACKFILE stream f from memory location p.
... to the stream f from the memory location pointed to by p.
+@retval
+ Returns the number of items written, which will be less than n if an
... bytes ...
+ error occurs. Error codes are stored in errno.
+@@char *@pack_fgets(char *p, int max, PACKFILE *f);
+@xref pack_fopen, pack_fopen_chunk, pack_fread, pack_getc
+ Reads a line from a PACKFILE stream, storing it at location p. Stops when
...from the stream f... the location pointed to by p.
+ a linefeed is encountered, or max bytes have been read. The end of line
...or 'max' bytes...
+ is handled by detecting optional '\r' characters optionally followed
Which character is optional here? Both if we consider the three text incoding
formats, right? Then a more generic wording (e.g. "by detecting the right
combination of characters for the platform.") would be better.
+ by '\n' characters. This supports CR-LF (DOS/Windows), LF (Unix), and
+ CR (Mac) formats.
+
+ Note, however, that the trailing carriage return is not included in the
+ retured string, in order to provide easy code portability across
...returned...
+ If you require this behaviour, use pack_fread() and/or pack_getc()
If you need the carriage return, ...
+@retval
+ Returns a pointer to where it stored the text, or NULL on error.
Returns the pointer p on success, ...
+
+@@int @pack_fputs(const char *p, PACKFILE *f);
+@xref pack_fopen, pack_fopen_chunk, pack_fwrite, pack_putc
+ Writes a string to a PACKFILE stream file. The input string is converted
... to the stream file f.
+ from the current text encoding format to UTF-8 before writing. Newline
+ characters (\n) are written as \r\n on DOS and Windows platforms. If you
What of the Mac platform here?
+ don't want this behaviour, use pack_fwrite() and/or pack_putc() instead.
+@retval
+ Returns zero on success, negative on error.
... or a negative number...
I know, I'm still as much picky as you can imagine :-)
--
Eric Botcazou