[Scummvm-cvs-logs] SF.net SVN: scummvm:[46375] tools/branches/gsoc2009-gui
fingolfin at users.sourceforge.net
fingolfin at users.sourceforge.net
Mon Dec 14 01:12:26 CET 2009
Revision: 46375
http://scummvm.svn.sourceforge.net/scummvm/?rev=46375&view=rev
Author: fingolfin
Date: 2009-12-14 00:12:26 +0000 (Mon, 14 Dec 2009)
Log Message:
-----------
TOOLS: Add lots of missing periods to doxygen comments; tweak some doxygen comments further
Modified Paths:
--------------
tools/branches/gsoc2009-gui/common/file.h
tools/branches/gsoc2009-gui/tool.h
Modified: tools/branches/gsoc2009-gui/common/file.h
===================================================================
--- tools/branches/gsoc2009-gui/common/file.h 2009-12-14 00:09:10 UTC (rev 46374)
+++ tools/branches/gsoc2009-gui/common/file.h 2009-12-14 00:12:26 UTC (rev 46375)
@@ -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 @@
/**
* 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 @@
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 @@
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 @@
/**
* 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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
*/
uint32 size() const;
- // FIXME: Remove this method ASAP
+ // FIXME: Remove this method eventually
FILE *getFileHandle() { return _file; }
protected:
Modified: tools/branches/gsoc2009-gui/tool.h
===================================================================
--- tools/branches/gsoc2009-gui/tool.h 2009-12-14 00:09:10 UTC (rev 46374)
+++ tools/branches/gsoc2009-gui/tool.h 2009-12-14 00:12:26 UTC (rev 46375)
@@ -84,22 +84,22 @@
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 @@
* Fatal error in the tool, throws a ToolException,
* you shouldn't really catch this exception.
*/
+ void error(const char *format, ...);
- void error(const char *format, ...);
/**
* A warning, the same as print but WARNING: is prepended to the message.
*/
+ void warning(const char *format, ...);
- 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 @@
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 @@
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 @@
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 @@
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 @@
/** 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:
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
More information about the Scummvm-git-logs
mailing list