mirror of
https://github.com/scummvm/scummvm-tools.git
synced 2026-05-21 05:40:44 +00:00
TOOLS: Add lots of missing periods to doxygen comments; tweak some doxygen comments further
svn-id: r46375
This commit is contained in:
Max Horn
+38
-34
@@ -28,8 +28,8 @@
|
||||
#include "tool_exception.h"
|
||||
|
||||
/**
|
||||
* Something unexpected happened while reading / writing to a file
|
||||
* Usually premature end, or that it could not be opened (write / read protected)
|
||||
* Something unexpected happened while reading / writing to a file.
|
||||
* Usually premature end, or that it could not be opened (write / read protected).
|
||||
*/
|
||||
class FileException : public ToolException {
|
||||
public:
|
||||
@@ -38,7 +38,7 @@ public:
|
||||
|
||||
/**
|
||||
* A file path, can be queried for different parts
|
||||
* and the parts can be modified seperately
|
||||
* and the parts can be modified separately.
|
||||
*/
|
||||
class Filename {
|
||||
public:
|
||||
@@ -95,7 +95,7 @@ public:
|
||||
bool empty() const;
|
||||
|
||||
/**
|
||||
* Returns true if the file exists, does NOT work for directories
|
||||
* Returns true if the file exists, does NOT work for directories.
|
||||
*/
|
||||
bool exists() const;
|
||||
|
||||
@@ -121,7 +121,7 @@ public:
|
||||
std::string getFullPath() const;
|
||||
|
||||
/**
|
||||
* Returns the filename (ie. strips all directories from the path)
|
||||
* Returns the filename (ie. strips all directories from the path).
|
||||
*/
|
||||
std::string getFullName() const;
|
||||
|
||||
@@ -162,13 +162,14 @@ public:
|
||||
/**
|
||||
* Opens the given file path as an in/out stream, depending on the
|
||||
* second argument.
|
||||
* File is always opened in binary mode
|
||||
* File is always opened in binary mode.
|
||||
*
|
||||
* @param filename The file to open
|
||||
* @param mode The mode to open the file in, can be either OR mask or in text
|
||||
*/
|
||||
File(const Filename &filename, FileMode mode);
|
||||
File(const Filename &filename, const char *mode);
|
||||
|
||||
/**
|
||||
* Create an empty file, used for two-step construction.
|
||||
*/
|
||||
@@ -186,12 +187,12 @@ public:
|
||||
void open(const Filename &filename, FileMode mode);
|
||||
|
||||
/**
|
||||
* Closes the file, if it's open
|
||||
* Closes the file, if it's open.
|
||||
*/
|
||||
void close();
|
||||
|
||||
/**
|
||||
* If the file is opened for reading / writing
|
||||
* Check whether the file is open.
|
||||
*/
|
||||
bool isOpen() const { return _file != 0; }
|
||||
|
||||
@@ -205,53 +206,53 @@ public:
|
||||
void setXorMode(uint8 xormode);
|
||||
|
||||
/**
|
||||
* Reads a single character (equivalent of fgetc
|
||||
* Reads a single character (equivalent of fgetc).
|
||||
*/
|
||||
int readChar();
|
||||
/**
|
||||
* Read a single unsigned byte.
|
||||
* Throws FileException if file is not open / if read failed.
|
||||
* @throws FileException if file is not open / if read failed.
|
||||
*/
|
||||
uint8 readByte();
|
||||
/**
|
||||
* Read a single 16-bit word, big endian.
|
||||
* Throws FileException if file is not open / if read failed.
|
||||
* @throws FileException if file is not open / if read failed.
|
||||
*/
|
||||
uint16 readUint16BE();
|
||||
/**
|
||||
* Read a single 16-bit word, little endian.
|
||||
* Throws FileException if file is not open / if read failed.
|
||||
* @throws FileException if file is not open / if read failed.
|
||||
*/
|
||||
uint16 readUint16LE();
|
||||
/**
|
||||
* Read a single 32-bit word, big endian.
|
||||
* Throws FileException if file is not open / if read failed.
|
||||
* @throws FileException if file is not open / if read failed.
|
||||
*/
|
||||
uint32 readUint32BE();
|
||||
/**
|
||||
* Read a single 32-bit word, little endian.
|
||||
* Throws FileException if file is not open / if read failed.
|
||||
* @throws FileException if file is not open / if read failed.
|
||||
*/
|
||||
uint32 readUint32LE();
|
||||
|
||||
/**
|
||||
* Read a single 16-bit word, big endian.
|
||||
* Throws FileException if file is not open / if read failed.
|
||||
* @throws FileException if file is not open / if read failed.
|
||||
*/
|
||||
int16 readSint16BE();
|
||||
/**
|
||||
* Read a single 16-bit word, little endian.
|
||||
* Throws FileException if file is not open / if read failed.
|
||||
* @throws FileException if file is not open / if read failed.
|
||||
*/
|
||||
int16 readSint16LE();
|
||||
/**
|
||||
* Read a single 32-bit word, big endian.
|
||||
* Throws FileException if file is not open / if read failed.
|
||||
* @throws FileException if file is not open / if read failed.
|
||||
*/
|
||||
int32 readSint32BE();
|
||||
/**
|
||||
* Read a single 32-bit word, little endian.
|
||||
* Throws FileException if file is not open / if read failed.
|
||||
* @throws FileException if file is not open / if read failed.
|
||||
*/
|
||||
int32 readSint32LE();
|
||||
|
||||
@@ -276,14 +277,14 @@ public:
|
||||
size_t read_noThrow(void *dataPtr, size_t dataSize);
|
||||
|
||||
/**
|
||||
* Reads a full string, until NULL or EOF
|
||||
* Throws FileException if file is not open / if read failed.
|
||||
* Reads a full string, until NULL or EOF.
|
||||
* @throws FileException if file is not open / if read failed.
|
||||
*/
|
||||
std::string readString();
|
||||
|
||||
/**
|
||||
* Reads the queried amount of bytes and returns it as a string
|
||||
* Throws FileException if file is not open / if read failed.
|
||||
* Reads the queried amount of bytes and returns it as a string.
|
||||
* @throws FileException if file is not open / if read failed.
|
||||
*
|
||||
* @param len How many bytes to read
|
||||
* @return the data read
|
||||
@@ -291,38 +292,38 @@ public:
|
||||
std::string readString(size_t len);
|
||||
|
||||
/**
|
||||
* Reads a string, using until NULL or EOF or CR/LF
|
||||
* Throws FileException if file is not open / if read failed.
|
||||
* Reads a string, using until NULL or EOF or CR/LF.
|
||||
* @throws FileException if file is not open / if read failed.
|
||||
*/
|
||||
void scanString(char *result);
|
||||
|
||||
/**
|
||||
* Writes a single character (equivalent of fputc)
|
||||
* Writes a single character (equivalent of fputc).
|
||||
*/
|
||||
void writeChar(int c);
|
||||
/**
|
||||
* Writes a single byte to the file.
|
||||
* Throws FileException if file is not open / if write failed.
|
||||
* @throws FileException if file is not open / if write failed.
|
||||
*/
|
||||
void writeByte(uint8 b);
|
||||
/**
|
||||
* Writes a single 16-bit word to the file, big endian.
|
||||
* Throws FileException if file is not open / if write failed.
|
||||
* @throws FileException if file is not open / if write failed.
|
||||
*/
|
||||
void writeUint16BE(uint16 value);
|
||||
/**
|
||||
* Writes a single 16-bit word to the file, little endian.
|
||||
* Throws FileException if file is not open / if write failed.
|
||||
* @throws FileException if file is not open / if write failed.
|
||||
*/
|
||||
void writeUint16LE(uint16 value);
|
||||
/**
|
||||
* Writes a single 32-bit word to the file, big endian.
|
||||
* Throws FileException if file is not open / if write failed.
|
||||
* @throws FileException if file is not open / if write failed.
|
||||
*/
|
||||
void writeUint32BE(uint32 value);
|
||||
/**
|
||||
* Writes a single 32-bit word to the file, little endian.
|
||||
* Throws FileException if file is not open / if write failed.
|
||||
* @throws FileException if file is not open / if write failed.
|
||||
*/
|
||||
void writeUint32LE(uint32 value);
|
||||
|
||||
@@ -337,7 +338,7 @@ public:
|
||||
size_t write(const void *dataPtr, size_t dataSize);
|
||||
|
||||
/**
|
||||
* Works the same as fprintf
|
||||
* Works the same as fprintf.
|
||||
*/
|
||||
void printf(const char *format, ...);
|
||||
|
||||
@@ -355,14 +356,17 @@ public:
|
||||
void rewind();
|
||||
|
||||
/**
|
||||
* Returns current position of the file cursor
|
||||
* Returns current position of the file cursor.
|
||||
*/
|
||||
int pos() const;
|
||||
|
||||
/**
|
||||
* Check whether an error occurred.
|
||||
*/
|
||||
int err() const;
|
||||
|
||||
/**
|
||||
* True if there is nothing more to read from this file
|
||||
* True if there is nothing more to read from this file.
|
||||
*/
|
||||
bool eos() const;
|
||||
|
||||
@@ -371,7 +375,7 @@ public:
|
||||
*/
|
||||
uint32 size() const;
|
||||
|
||||
// FIXME: Remove this method ASAP
|
||||
// FIXME: Remove this method eventually
|
||||
FILE *getFileHandle() { return _file; }
|
||||
|
||||
protected:
|
||||
|
||||
@@ -84,22 +84,22 @@ public:
|
||||
int run(const std::deque<std::string> &args);
|
||||
|
||||
/**
|
||||
* Parse with args set already (modify the public members to set them)
|
||||
* Exceptions are not caught, so this function may throw
|
||||
* Parse with args set already (modify the public members to set them).
|
||||
* Exceptions are not caught, so this function may throw.
|
||||
*/
|
||||
void run();
|
||||
|
||||
/**
|
||||
* Returns true if the file appears to be a valid input to this tool,
|
||||
* Default implementation always return true
|
||||
* Returns true if the file appears to be a valid input to this tool.
|
||||
* Default implementation always return true.
|
||||
*
|
||||
* @param filename The file to inspect
|
||||
*/
|
||||
virtual InspectionMatch inspectInput(const Filename &filename);
|
||||
|
||||
/**
|
||||
* Aborts executing of the tool, can be called from another thread
|
||||
* The progress will not be aborted until the next call to notifyProgress
|
||||
* Aborts executing of the tool, can be called from another thread.
|
||||
* The progress will not be aborted until the next call to notifyProgress.
|
||||
*/
|
||||
void abort();
|
||||
|
||||
@@ -107,43 +107,45 @@ public:
|
||||
* Fatal error in the tool, throws a ToolException,
|
||||
* you shouldn't really catch this exception.
|
||||
*/
|
||||
|
||||
void error(const char *format, ...);
|
||||
|
||||
/**
|
||||
* A warning, the same as print but WARNING: is prepended to the message.
|
||||
*/
|
||||
|
||||
void warning(const char *format, ...);
|
||||
|
||||
/**
|
||||
* Prints a message, to either stdout or the GUI, always use this instead of printf
|
||||
* Prints a message, to either stdout or the GUI, always use this
|
||||
* instead of printf.
|
||||
*/
|
||||
void print(const char *format, ...);
|
||||
|
||||
/** Returns name of the tool */
|
||||
/** Returns name of the tool. */
|
||||
std::string getName() const;
|
||||
|
||||
/** Returns the helpstring of the tool */
|
||||
/** Returns the helpstring of the tool. */
|
||||
virtual std::string getHelp() const;
|
||||
|
||||
/** Returns the helpstring of the tool */
|
||||
/** Returns the short helpstring of the tool. */
|
||||
virtual std::string getShortHelp() const;
|
||||
|
||||
/** Returns the type of the tool */
|
||||
/** Returns the type of the tool. */
|
||||
ToolType getType() const;
|
||||
|
||||
/**
|
||||
* Notifies of progress, normally just prints a dot if enough time has passed since the last call
|
||||
* Notifies of progress, normally just prints a dot if enough time
|
||||
* has passed since the last call.
|
||||
* This may through an AbortException, you should generally not catch this
|
||||
* (more than to do cleanup)
|
||||
* (except for doing cleanup).
|
||||
*
|
||||
* @param print_dot Provides visual feedback to the user, defaults to true
|
||||
*/
|
||||
void notifyProgress(bool print_dot = true);
|
||||
|
||||
/**
|
||||
* Update progress in a more distinct way, if we know the estimated runtime
|
||||
* Update progress in a more distinct way, if we know the estimated runtime.
|
||||
* This may through an AbortException, you should generally not catch this
|
||||
* (more than to do cleanup)
|
||||
* (except for doing cleanup).
|
||||
*
|
||||
* @param done how many parts that have been done
|
||||
* @param total parts in total
|
||||
@@ -151,15 +153,16 @@ public:
|
||||
void updateProgress(int done, int total = 100);
|
||||
|
||||
/**
|
||||
* Spawns a subprocess with the given commandline
|
||||
* this acts exactly the same as 'system()', but hides the process window
|
||||
* Spawns a subprocess with the given commandline.
|
||||
* This acts exactly the same as 'system()', but hides the process window.
|
||||
*
|
||||
* @param cmd The commandline to run
|
||||
*/
|
||||
int spawnSubprocess(const char *cmd);
|
||||
|
||||
/**
|
||||
* This function sets the function which will be called needs to output something
|
||||
* This function sets the function which will be called needs to
|
||||
* output something.
|
||||
*
|
||||
* @param f the function to be called, it takes a userdata argument in addition to text to print
|
||||
* @param udata The userdata to call to the print function each time it is called
|
||||
@@ -167,9 +170,9 @@ public:
|
||||
void setPrintFunction(void f(void *, const char *), void *udata);
|
||||
|
||||
/**
|
||||
* Set the function that is called on status updates
|
||||
* Set the function that is called on status updates.
|
||||
* Parameters to the function are 'done' and 'total', if total is 0,
|
||||
* it's a simple status notification (print a dot or something)
|
||||
* it's a simple status notification (print a dot or something).
|
||||
*
|
||||
* @param f this function will be called with udata arguments and 'done' / 'total'
|
||||
* @param udata Userdata that will be passed to the function on each call
|
||||
@@ -177,8 +180,8 @@ public:
|
||||
void setProgressFunction(void f(void *, int, int), void *udata);
|
||||
|
||||
/**
|
||||
* Sets the function to use to execute a process
|
||||
* this defaults to the function 'system()', GUI overloads this
|
||||
* Sets the function to use to execute a process.
|
||||
* This defaults to the function 'system()', GUI overloads this
|
||||
* to not spawn a window.
|
||||
*
|
||||
* @param f this function will be called when a process needs to be spawned
|
||||
@@ -190,27 +193,27 @@ protected:
|
||||
virtual void parseAudioArguments();
|
||||
void parseOutputArguments();
|
||||
|
||||
// Parses the arguments only this tool takes
|
||||
/** Parses the arguments only this tool takes. */
|
||||
virtual void parseExtraArguments();
|
||||
|
||||
// Runs the internal tool (the 'main')
|
||||
/** Runs the internal tool (the 'main'). */
|
||||
virtual void execute() = 0;
|
||||
|
||||
public:
|
||||
|
||||
/** List of all inputs this tool expects, also contains the paths filled in */
|
||||
/** List of all inputs this tool expects, also contains the paths filled in. */
|
||||
ToolInputs _inputPaths;
|
||||
|
||||
// Output
|
||||
Filename _outputPath;
|
||||
|
||||
protected:
|
||||
/* Command line arguments we are parsing. */
|
||||
/** Command line arguments we are parsing. */
|
||||
std::deque<std::string> _arguments;
|
||||
|
||||
/** If this tools outputs to a directory, not a file. */
|
||||
bool _outputToDirectory;
|
||||
/** If this tool can display output progress in % */
|
||||
/** If this tool can display output progress in percent. */
|
||||
bool _supportsProgressBar;
|
||||
|
||||
/** Name of the tool. */
|
||||
@@ -222,7 +225,7 @@ protected:
|
||||
/** The text to display to help the user. */
|
||||
std::string _shorthelp;
|
||||
|
||||
/** Status of internal abort flag, if set, next call to *Progress will throw */
|
||||
/** Status of internal abort flag, if set, next call to *Progress will throw. */
|
||||
bool _abort;
|
||||
|
||||
private:
|
||||
|
||||
Reference in New Issue
Block a user