From 29b1c842f21928a53ea630d36c40bf9a9bd0986e Mon Sep 17 00:00:00 2001 From: Antidote Date: Sat, 26 Jan 2013 17:19:49 -0800 Subject: [PATCH] * Completed documentation --- include/BinaryReader.hpp | 14 +++ include/BinaryWriter.hpp | 130 ++++++++++++++++++--- include/Exception.hpp | 33 +++++- include/FileNotFoundException.hpp | 37 +++++- include/IOException.hpp | 33 +++++- include/InvalidOperationException.hpp | 31 ++++- include/Stream.hpp | 20 +++- include/Types.hpp | 14 +++ libzelda.depend | 160 -------------------------- libzelda.layout | 9 -- src/BinaryReader.cpp | 15 +++ src/BinaryWriter.cpp | 15 +++ src/Stream.cpp | 15 +++ src/utility.cpp | 15 +++ 14 files changed, 347 insertions(+), 194 deletions(-) delete mode 100644 libzelda.depend delete mode 100644 libzelda.layout diff --git a/include/BinaryReader.hpp b/include/BinaryReader.hpp index 8f507ef..3c7f2ff 100644 --- a/include/BinaryReader.hpp +++ b/include/BinaryReader.hpp @@ -1,3 +1,17 @@ +// This file is part of libZelda. +// +// libZelda is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// libZelda is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. +// +// You should have received a copy of the GNU General Public License +// along with libZelda. If not, see #ifndef __BINARYREADER_HPP__ #define __BINARYREADER_HPP__ diff --git a/include/BinaryWriter.hpp b/include/BinaryWriter.hpp index 26484b7..06b7913 100644 --- a/include/BinaryWriter.hpp +++ b/include/BinaryWriter.hpp @@ -1,3 +1,17 @@ +// This file is part of libZelda. +// +// libZelda is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// libZelda is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. +// +// You should have received a copy of the GNU General Public License +// along with libZelda. If not, see #ifndef __BINARYWRITER_HPP__ #define __BINARYWRITER_HPP__ @@ -13,21 +27,109 @@ */ class BinaryWriter : public Stream { -public: - BinaryWriter(const Uint8* data, Uint64 length); - BinaryWriter(const Stream& stream); - BinaryWriter(const std::string& filename); +public: + /*! \brief This constructor takes an existing buffer to write to. + * + * \param data The existing buffer + * \param length The length of the existing buffer + */ + BinaryWriter(const Uint8* data, Uint64 length); + + /*! \brief This constructor takes an existing Stream to write to. + * + * \param stream The stream to write data to + */ + BinaryWriter(const Stream& stream); + /*! \brief This constructor creates an instance from a file on disk. + * + * \param filename The file to create the stream from + */ + BinaryWriter(const std::string& filename); + + /*! \brief Saves the file to the specified file. + * + * \param filename If not empty, the filename to save to + */ void save(const std::string& filename=""); - - void writeInt16(Int16); - void writeUInt16(Uint16); - void writeInt32(Int32); - void writeUInt32(Uint32); - void writeInt64(Int64); - void writeUInt64(Uint64); - void writeFloat(float); - void writeDouble(double); - void writeBool(bool); + + /*! \brief Writes an Int16 to the buffer and advances the buffer. + * It also swaps the bytes depending on the platform and Stream settings. + * + * \sa Endian + * \param val The value to write to the buffer + */ + void writeInt16(Int16 val); + + /*! \brief Writes an Uint16 to the buffer and advances the buffer. + * It also swaps the bytes depending on the platform and Stream settings + * + * \sa Endian + * \param val The value to write to the buffer + */ + void writeUInt16(Uint16); + + /*! \brief Writes an Int32 to the buffer and advances the buffer. + * It also swaps the bytes depending on the platform and Stream settings. + * + * \sa Endian + * \param val The value to write to the buffer + */ + void writeInt32(Int32); + + /*! \brief Writes an Uint32 to the buffer and advances the buffer. + * It also swaps the bytes depending on the platform and Stream settings. + * + * \sa Endian + * \param val The value to write to the buffer + */ + void writeUInt32(Uint32); + + /*! \brief Writes an Int64 to the buffer and advances the buffer. + * It also swaps the bytes depending on the platform and Stream settings. + * + * \sa Endian + * \param val The value to write to the buffer + */ + void writeInt64(Int64); + + /*! \brief Writes an Uint64 to the buffer and advances the buffer. + * It also swaps the bytes depending on the platform and Stream settings. + * + * \sa Endian + * \param val The value to write to the buffer + */ + void writeUInt64(Uint64); + + /*! \brief Writes an float to the buffer and advances the buffer. + * It also swaps the bytes depending on the platform and Stream settings. + * + * \sa Endian + * \param val The value to write to the buffer + */ + void writeFloat(float); + + /*! \brief Writes an double to the buffer and advances the buffer. + * It also swaps the bytes depending on the platform and Stream settings. + * + * \sa Endian + * \param val The value to write to the buffer + */ + void writeDouble(double); + + /*! \brief Writes an bool to the buffer and advances the buffer. + * It also swaps the bytes depending on the platform and Stream settings. + * + * \sa Endian + * \param val The value to write to the buffer + */ + void writeBool(bool); + + /*! \brief Writes an unicode string to the buffer and advances the buffer. + * It also swaps the bytes depending on the platform and Stream settings. + * + * \sa Endian + * \param str The string to write to the buffer + */ void writeUnicode(const std::string& str); private: Int8 readByte(); diff --git a/include/Exception.hpp b/include/Exception.hpp index 9f1b61a..74011b5 100644 --- a/include/Exception.hpp +++ b/include/Exception.hpp @@ -1,15 +1,42 @@ +// This file is part of libZelda. +// +// libZelda is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// libZelda is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. +// +// You should have received a copy of the GNU General Public License +// along with libZelda. If not, see + #ifndef __EXCEPTION_HPP__ #define __EXCEPTION_HPP__ #include - + +/*! \class Exception + * \brief The baseclass for all Exceptions. + * + * Do Not use Exception directly, instead create an appropriate + * Exception class and inherit from this baseclass. + */ class Exception { -public: +public: + /*! \brief The constructor for an Exception + * \param message The error message to throw + */ Exception(const std::string& message) : m_message(message) {}; - + + /*! \brief Returns the Error message of the exception + * \return std::string The error message + */ std::string message() const { return m_message; diff --git a/include/FileNotFoundException.hpp b/include/FileNotFoundException.hpp index d2aef89..ba6a059 100644 --- a/include/FileNotFoundException.hpp +++ b/include/FileNotFoundException.hpp @@ -1,16 +1,47 @@ +// This file is part of libZelda. +// +// libZelda is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// libZelda is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. +// +// You should have received a copy of the GNU General Public License +// along with libZelda. If not, see + #ifndef __FILENOTFOUNDEXCEPTION_HPP__ #define __FILENOTFOUNDEXCEPTION_HPP__ #include "Exception.hpp" - + +/*! \class FileNotFoundException + * \brief An excpeption thrown when a file could not be found at the given path. + * + * This should only be thrown when the library tries to write to a buffer + * e.g when the position is greater than the position and the stream + * is not set to autoresize.
+ *
+ * It is NOT appropriate to use throw new so avoid doing so, + * keeping things on the stack as much as possible is very important for speed. + */ class FileNotFoundException : public Exception { -public: +public: + /*! \brief The constructor for an FileNotFoundException + * \param filename The path of the offending file. + */ FileNotFoundException(const std::string& filename) : Exception("FileNotFoundException:\nCouldn't not find \"" + filename + "\", please check that it exists."), m_filename(filename) {} - + + /*! \brief Returns the path of the offending file. + * \return std::string The filename of the file including the path. + */ std::string filename() const { return m_filename; } private: std::string m_filename; diff --git a/include/IOException.hpp b/include/IOException.hpp index 88a2b99..51d6966 100644 --- a/include/IOException.hpp +++ b/include/IOException.hpp @@ -1,11 +1,40 @@ +// This file is part of libZelda. +// +// libZelda is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// libZelda is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. +// +// You should have received a copy of the GNU General Public License +// along with libZelda. If not, see + #ifndef __IOEXCEPTION_HPP__ #define __IOEXCEPTION_HPP__ #include "Exception.hpp" - + + +/*! \class IOException + * \brief An excpeption thrown on inappropriate IO calls. + * + * This should only be thrown when the library tries to write to a buffer + * e.g when the position is greater than the position and the stream + * is not set to autoresize.
+ *
+ * It is NOT appropriate to use throw new so avoid doing so, + * keeping things on the stack as much as possible is very important for speed. + */ class IOException : public Exception { -public: +public: + /*! \brief The constructor for an IOException + * \param message The error message to throw + */ IOException(const std::string& message) : Exception("IOException: " + message) {}; diff --git a/include/InvalidOperationException.hpp b/include/InvalidOperationException.hpp index 36fb95b..ce5f753 100644 --- a/include/InvalidOperationException.hpp +++ b/include/InvalidOperationException.hpp @@ -1,12 +1,39 @@ +// This file is part of libZelda. +// +// libZelda is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// libZelda is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. +// +// You should have received a copy of the GNU General Public License +// along with libZelda. If not, see + #ifndef __INVALID_OPERATION_EXCEPTION_HPP__ #define __INVALID_OPERATION_EXCEPTION_HPP__ #include #include - + +/*! \class InvalidOperationException + * \brief An excpeption thrown on Invalid Operations calls. + * + * This should only be thrown when the library tries to + * e.g pass a NULL pointer to a function which requires a valid pointer. + *
+ * It is NOT appropriate to use throw new so avoid doing so, + * keeping things on the stack as much as possible is very important for speed. + */ class InvalidOperationException : public Exception { -public: +public: + /*! \brief The constructor for an InvalidOperationException + * \param error The error message to throw + */ InvalidOperationException(const std::string& error) : Exception("InvalidOperationException:\n" + error) { diff --git a/include/Stream.hpp b/include/Stream.hpp index d4e6bdf..2312d32 100644 --- a/include/Stream.hpp +++ b/include/Stream.hpp @@ -1,3 +1,17 @@ +// This file is part of libZelda. +// +// libZelda is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// libZelda is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. +// +// You should have received a copy of the GNU General Public License +// along with libZelda. If not, see #ifndef __STREAM_HPP__ #define __STREAM_HPP__ @@ -60,7 +74,11 @@ public: * * \param stream The stream to read data from */ - Stream(Stream* stream); + Stream(Stream* stream); + + /*! \brief The destructor cleans up memory and sets everything back + * to the default settings. + */ virtual ~Stream(); /*! \brief Writes a bit at the current position and advances the position by one bit. diff --git a/include/Types.hpp b/include/Types.hpp index 739e934..75f23f5 100644 --- a/include/Types.hpp +++ b/include/Types.hpp @@ -1,3 +1,17 @@ +// This file is part of libZelda. +// +// libZelda is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// libZelda is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. +// +// You should have received a copy of the GNU General Public License +// along with libZelda. If not, see #ifndef __TYPES_HPP__ #define __TYPES_HPP__ diff --git a/libzelda.depend b/libzelda.depend deleted file mode 100644 index a6cce7d..0000000 --- a/libzelda.depend +++ /dev/null @@ -1,160 +0,0 @@ -# depslib dependency file v1.0 -1359172369 source:/home/antidote/trunk/save editor/libzelda/src/BinaryReader.cpp - "BinaryReader.hpp" - "IOException.hpp" - "FileNotFoundException.hpp" - "utility.hpp" - "utf8.h" - - - - -1359171705 /home/antidote/trunk/save editor/libzelda/include/BinaryReader.hpp - "Stream.hpp" - - -1358872986 /home/antidote/trunk/save editor/libzelda/include/Stream.hpp - "Types.hpp" - -1358872986 /home/antidote/trunk/save editor/libzelda/include/Types.hpp - - -1358872986 /home/antidote/trunk/save editor/libzelda/include/IOException.hpp - "Exception.hpp" - -1358872986 /home/antidote/trunk/save editor/libzelda/include/Exception.hpp - - -1358872986 /home/antidote/trunk/save editor/libzelda/include/FileNotFoundException.hpp - "Exception.hpp" - -1359171946 /home/antidote/trunk/save editor/libzelda/include/utility.hpp - - "Types.hpp" - -1358872986 /home/antidote/trunk/save editor/libzelda/include/utf8.h - "utf8/checked.h" - "utf8/unchecked.h" - -1358872986 /home/antidote/trunk/save editor/libzelda/include/utf8/checked.h - "core.h" - - -1358872986 /home/antidote/trunk/save editor/libzelda/include/utf8/core.h - - -1358872986 /home/antidote/trunk/save editor/libzelda/include/utf8/unchecked.h - "core.h" - -1359172754 source:/home/antidote/trunk/save editor/libzelda/src/BinaryWriter.cpp - "BinaryWriter.hpp" - "IOException.hpp" - "FileNotFoundException.hpp" - "utility.hpp" - "utf8.h" - - - - - -1358872986 /home/antidote/trunk/save editor/libzelda/include/BinaryWriter.hpp - "Stream.hpp" - - -1358872986 source:/home/antidote/trunk/save editor/libzelda/src/Stream.cpp - "Stream.hpp" - "IOException.hpp" - "InvalidOperationException.hpp" - - - -1358872986 /home/antidote/trunk/save editor/libzelda/include/InvalidOperationException.hpp - - - -1359219210 source:/home/antidote/trunk/save editor/libzelda/src/utility.cpp - "utility.hpp" - - - - -1359243487 source:/home/antidote/wiiking2_editor/libzelda/src/BinaryWriter.cpp - "BinaryWriter.hpp" - "IOException.hpp" - "FileNotFoundException.hpp" - "utility.hpp" - "utf8.h" - - - - - -1359245518 /home/antidote/wiiking2_editor/libzelda/include/BinaryWriter.hpp - "Stream.hpp" - - -1359243334 /home/antidote/wiiking2_editor/libzelda/include/Stream.hpp - "Types.hpp" - -1358872986 /home/antidote/wiiking2_editor/libzelda/include/Types.hpp - - -1358872986 /home/antidote/wiiking2_editor/libzelda/include/IOException.hpp - "Exception.hpp" - -1358872986 /home/antidote/wiiking2_editor/libzelda/include/Exception.hpp - - -1358872986 /home/antidote/wiiking2_editor/libzelda/include/FileNotFoundException.hpp - "Exception.hpp" - -1359171946 /home/antidote/wiiking2_editor/libzelda/include/utility.hpp - - "Types.hpp" - -1358872986 /home/antidote/wiiking2_editor/libzelda/include/utf8.h - "utf8/checked.h" - "utf8/unchecked.h" - -1358872986 /home/antidote/wiiking2_editor/libzelda/include/utf8/checked.h - "core.h" - - -1358872986 /home/antidote/wiiking2_editor/libzelda/include/utf8/core.h - - -1358872986 /home/antidote/wiiking2_editor/libzelda/include/utf8/unchecked.h - "core.h" - -1359243354 source:/home/antidote/wiiking2_editor/libzelda/src/Stream.cpp - "Stream.hpp" - "IOException.hpp" - "InvalidOperationException.hpp" - - - -1358872986 /home/antidote/wiiking2_editor/libzelda/include/InvalidOperationException.hpp - - - -1359219210 source:/home/antidote/wiiking2_editor/libzelda/src/utility.cpp - "utility.hpp" - - - - -1359243404 source:/home/antidote/wiiking2_editor/libzelda/src/BinaryReader.cpp - "BinaryReader.hpp" - "IOException.hpp" - "FileNotFoundException.hpp" - "utility.hpp" - "utf8.h" - - - - - -1359220647 /home/antidote/wiiking2_editor/libzelda/include/BinaryReader.hpp - "Stream.hpp" - - diff --git a/libzelda.layout b/libzelda.layout deleted file mode 100644 index 85d4c82..0000000 --- a/libzelda.layout +++ /dev/null @@ -1,9 +0,0 @@ - - - - - - - - - diff --git a/src/BinaryReader.cpp b/src/BinaryReader.cpp index 3969098..716fb29 100644 --- a/src/BinaryReader.cpp +++ b/src/BinaryReader.cpp @@ -1,3 +1,18 @@ +// This file is part of libZelda. +// +// libZelda is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// libZelda is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. +// +// You should have received a copy of the GNU General Public License +// along with libZelda. If not, see + #include "BinaryReader.hpp" #include "IOException.hpp" #include "FileNotFoundException.hpp" diff --git a/src/BinaryWriter.cpp b/src/BinaryWriter.cpp index 10b4383..d6a44bd 100644 --- a/src/BinaryWriter.cpp +++ b/src/BinaryWriter.cpp @@ -1,3 +1,18 @@ +// This file is part of libZelda. +// +// libZelda is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// libZelda is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. +// +// You should have received a copy of the GNU General Public License +// along with libZelda. If not, see + #include "BinaryWriter.hpp" #include "IOException.hpp" #include "FileNotFoundException.hpp" diff --git a/src/Stream.cpp b/src/Stream.cpp index 3b5ac76..79ad90f 100644 --- a/src/Stream.cpp +++ b/src/Stream.cpp @@ -1,3 +1,18 @@ +// This file is part of libZelda. +// +// libZelda is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// libZelda is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. +// +// You should have received a copy of the GNU General Public License +// along with libZelda. If not, see + #include "Stream.hpp" #include "IOException.hpp" #include "InvalidOperationException.hpp" diff --git a/src/utility.cpp b/src/utility.cpp index 74eae0d..2bd5ace 100644 --- a/src/utility.cpp +++ b/src/utility.cpp @@ -1,3 +1,18 @@ +// This file is part of libZelda. +// +// libZelda is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// libZelda is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. +// +// You should have received a copy of the GNU General Public License +// along with libZelda. If not, see + #include "utility.hpp" #include #include