From 6c9078fd30097b38537a60fbecb9828da69c3517 Mon Sep 17 00:00:00 2001 From: rubidium Date: Tue, 18 Jan 2011 22:17:15 +0000 Subject: (svn r21844) -Codechange: move documentation towards the code to make it more likely to be updates [a-c]. --- src/crashlog.cpp | 74 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) (limited to 'src/crashlog.cpp') diff --git a/src/crashlog.cpp b/src/crashlog.cpp index e47a65ed7..bda4d674f 100644 --- a/src/crashlog.cpp +++ b/src/crashlog.cpp @@ -73,6 +73,12 @@ char *CrashLog::LogCompiler(char *buffer, const char *last) const return buffer; } +/** + * Writes OpenTTD's version to the buffer. + * @param buffer The begin where to write at. + * @param last The last position in the buffer to write to. + * @return the position of the \c '\0' character after the buffer. + */ char *CrashLog::LogOpenTTDVersion(char *buffer, const char *last) const { return buffer + seprintf(buffer, last, @@ -105,6 +111,13 @@ char *CrashLog::LogOpenTTDVersion(char *buffer, const char *last) const ); } +/** + * Writes the (important) configuration settings to the buffer. + * E.g. graphics set, sound set, blitter and AIs. + * @param buffer The begin where to write at. + * @param last The last position in the buffer to write to. + * @return the position of the \c '\0' character after the buffer. + */ char *CrashLog::LogConfiguration(char *buffer, const char *last) const { buffer += seprintf(buffer, last, @@ -181,6 +194,12 @@ char *CrashLog::LogConfiguration(char *buffer, const char *last) const # include #endif +/** + * Writes information (versions) of the used libraries. + * @param buffer The begin where to write at. + * @param last The last position in the buffer to write to. + * @return the position of the \c '\0' character after the buffer. + */ char *CrashLog::LogLibraries(char *buffer, const char *last) const { buffer += seprintf(buffer, last, "Libraries:\n"); @@ -243,11 +262,21 @@ char *CrashLog::LogLibraries(char *buffer, const char *last) const return buffer; } +/** + * Helper function for printing the gamelog. + * @param s the string to print. + */ /* static */ void CrashLog::GamelogFillCrashLog(const char *s) { CrashLog::gamelog_buffer += seprintf(CrashLog::gamelog_buffer, CrashLog::gamelog_last, "%s\n", s); } +/** + * Writes the gamelog data to the buffer. + * @param buffer The begin where to write at. + * @param last The last position in the buffer to write to. + * @return the position of the \c '\0' character after the buffer. + */ char *CrashLog::LogGamelog(char *buffer, const char *last) const { CrashLog::gamelog_buffer = buffer; @@ -256,6 +285,12 @@ char *CrashLog::LogGamelog(char *buffer, const char *last) const return CrashLog::gamelog_buffer + seprintf(CrashLog::gamelog_buffer, last, "\n"); } +/** + * Fill the crash log buffer with all data of a crash log. + * @param buffer The begin where to write at. + * @param last The last position in the buffer to write to. + * @return the position of the \c '\0' character after the buffer. + */ char *CrashLog::FillCrashLog(char *buffer, const char *last) const { time_t cur_time = time(NULL); @@ -281,6 +316,15 @@ char *CrashLog::FillCrashLog(char *buffer, const char *last) const return buffer; } +/** + * Write the crash log to a file. + * @note On success the filename will be filled with the full path of the + * crash log file. Make sure filename is at least \c MAX_PATH big. + * @param buffer The begin of the buffer to write to the disk. + * @param filename Output for the filename of the written file. + * @param filename_last The last position in the filename buffer. + * @return true when the crash log was successfully written. + */ bool CrashLog::WriteCrashLog(const char *buffer, char *filename, const char *filename_last) const { seprintf(filename, filename_last, "%scrash.log", _personal_dir); @@ -301,6 +345,14 @@ bool CrashLog::WriteCrashLog(const char *buffer, char *filename, const char *fil return 0; } +/** + * Write the (crash) savegame to a file. + * @note On success the filename will be filled with the full path of the + * crash save file. Make sure filename is at least \c MAX_PATH big. + * @param filename Output for the filename of the written file. + * @param filename_last The last position in the filename buffer. + * @return true when the crash save was successfully made. + */ bool CrashLog::WriteSavegame(char *filename, const char *filename_last) const { /* If the map array doesn't exist, saving will fail too. If the map got @@ -319,6 +371,14 @@ bool CrashLog::WriteSavegame(char *filename, const char *filename_last) const } } +/** + * Write the (crash) screenshot to a file. + * @note On success the filename will be filled with the full path of the + * screenshot. Make sure filename is at least \c MAX_PATH big. + * @param filename Output for the filename of the written file. + * @param filename_last The last position in the filename buffer. + * @return true when the crash screenshot was successfully made. + */ bool CrashLog::WriteScreenshot(char *filename, const char *filename_last) const { /* Don't draw when we have invalid screen size */ @@ -329,6 +389,12 @@ bool CrashLog::WriteScreenshot(char *filename, const char *filename_last) const return res; } +/** + * Makes the crash log, writes it to a file and then subsequently tries + * to make a crash dump and crash savegame. It uses DEBUG to write + * information like paths to the console. + * @return true when everything is made successfully. + */ bool CrashLog::MakeCrashLog() const { /* Don't keep looping logging crashes. */ @@ -384,11 +450,19 @@ bool CrashLog::MakeCrashLog() const return ret; } +/** + * Sets a message for the error message handler. + * @param message The error message of the error. + */ /* static */ void CrashLog::SetErrorMessage(const char *message) { CrashLog::message = message; } +/** + * Try to close the sound/video stuff so it doesn't keep lingering around + * incorrect video states or so, e.g. keeping dpmi disabled. + */ /* static */ void CrashLog::AfterCrashLogCleanup() { if (_music_driver != NULL) _music_driver->Stop(); -- cgit v1.2.3-54-g00ecf