Filled in more documentation.

This commit is contained in:
Ryan C. Gordon 2017-08-14 01:28:30 -04:00
parent dd68246737
commit 9c9325c2c5
2 changed files with 35 additions and 4 deletions

View File

@ -3625,7 +3625,17 @@ typedef struct PHYSFS_Archiver
* \fn int PHYSFS_registerArchiver(const PHYSFS_Archiver *archiver)
* \brief Add a new archiver to the system.
*
* !!! FIXME-3.0: write me.
* \warning This is advanced, hardcore stuff. You don't need this unless you
* really know what you're doing. Most apps will not need this.
*
* If you want to provide your own archiver (for example, a custom archive
* file format, or some virtual thing you want to make look like a filesystem
* that you can access through the usual PhysicsFS APIs), this is where you
* start. Once an archiver is successfully registered, then you can use
* PHYSFS_mount() to add archives that your archiver supports to the
* search path, or perhaps use it as the write dir. Internally, PhysicsFS
* uses this function to register its own built-in archivers, like .zip
* support, etc.
*
* You may not have two archivers that handle the same extension. If you are
* going to have a clash, you can deregister the other archiver (including
@ -3634,6 +3644,9 @@ typedef struct PHYSFS_Archiver
* The data in (archiver) is copied; you may free this pointer when this
* function returns.
*
* Once this function returns successfully, PhysicsFS will be able to support
* archives of this type until you deregister the archiver again.
*
* \param archiver The archiver to register.
* \return Zero on error, non-zero on success.
*
@ -3646,10 +3659,22 @@ PHYSFS_DECL int PHYSFS_registerArchiver(const PHYSFS_Archiver *archiver);
* \fn int PHYSFS_deregisterArchiver(const char *ext)
* \brief Remove an archiver from the system.
*
* !!! FIXME-3.0: write me.
* If for some reason, you only need your previously-registered archiver to
* live for a portion of your app's lifetime, you can remove it from the
* system once you're done with it through this function.
*
* This fails if there are any archives still open that use this archiver.
*
* This function can also remove internally-supplied archivers, like .zip
* support or whatnot. This could be useful in some situations, like
* disabling support for them outright or overriding them with your own
* implementation. Once an internal archiver is disabled like this,
* PhysicsFS provides no mechanism to recover them, short of calling
* PHYSFS_deinit() and PHYSFS_init() again.
*
* PHYSFS_deinit() will automatically deregister all archivers, so you don't
* need to explicitly deregister yours if you otherwise shut down cleanly.
*
* \param ext Filename extension that the archiver handles.
* \return Zero on error, non-zero on success.
*

View File

@ -356,7 +356,7 @@ int UNPK_stat(void *opaque, const char *fn, PHYSFS_Stat *st);
/* Optional API many archivers use this to manage their directory tree. */
/* !!! FIXME-3.0: document this better. */
/* !!! FIXME: document this better. */
typedef struct __PHYSFS_DirTreeEntry
{
@ -544,7 +544,13 @@ PHYSFS_sint64 __PHYSFS_platformFileLength(void *handle);
/*
* !!! FIXME-3.0: comment me.
* Read filesystem metadata for a specific path.
*
* This needs to fill in all the fields of (stat). For fields that might not
* mean anything on a platform (access time, perhaps), choose a reasonable
* default.
*
* Return zero on failure, non-zero on success.
*/
int __PHYSFS_platformStat(const char *fn, PHYSFS_Stat *stat);