From b0fa4422f27859785be5815b52e2a7c4918f6a60 Mon Sep 17 00:00:00 2001 From: Jason Felds Date: Sat, 12 Feb 2011 22:20:11 -0500 Subject: [PATCH] Course*CRS.* doxygen-ated. --- src/CourseLoaderCRS.cpp | 7 +++++++ src/CourseLoaderCRS.h | 43 ++++++++++++++++++++++++++++++++++++++--- src/CourseWriterCRS.cpp | 6 ++++++ src/CourseWriterCRS.h | 32 +++++++++++++++++++++++++++--- 4 files changed, 82 insertions(+), 6 deletions(-) diff --git a/src/CourseLoaderCRS.cpp b/src/CourseLoaderCRS.cpp index 55ff77af97..e780b7b0d1 100644 --- a/src/CourseLoaderCRS.cpp +++ b/src/CourseLoaderCRS.cpp @@ -16,8 +16,10 @@ #include "CourseUtil.h" #include +/** @brief Edit courses can only be so big before they are rejected. */ const int MAX_EDIT_COURSE_SIZE_BYTES = 32*1024; // 32KB +/** @brief The list of difficulty names for courses. */ const char *g_CRSDifficultyNames[] = { "Beginner", @@ -28,6 +30,11 @@ const char *g_CRSDifficultyNames[] = "Edit", }; +/** + * @brief Retrieve the course difficulty based on the string name. + * @param s the name of the difficulty. + * @return the course difficulty. + */ static CourseDifficulty CRSStringToDifficulty( const RString& s ) { FOREACH_ENUM( Difficulty,i) diff --git a/src/CourseLoaderCRS.h b/src/CourseLoaderCRS.h index 574a87bbf8..e03081a3f4 100644 --- a/src/CourseLoaderCRS.h +++ b/src/CourseLoaderCRS.h @@ -1,4 +1,4 @@ -/* CourseLoaderCRS - Reads a Course from an .CRS file. */ +/** @brief CourseLoaderCRS - Reads a Course from an .CRS file. */ #ifndef COURSE_LOADER_CRS_H #define COURSE_LOADER_CRS_H @@ -7,19 +7,56 @@ class Course; class MsdFile; +/** @brief The Course Loader handles parsing the .crs files. */ namespace CourseLoaderCRS { + /** + * @brief Attempt to load a course file from a particular path. + * @param sPath the path to the file. + * @param out the course file. + * @return its success or failure. + */ bool LoadFromCRSFile( const RString &sPath, Course &out ); + /** + * @brief Attempt to load the course information from the msd context. + * @param sPath the path to the file. + * @param msd the MSD context. + * @param out the course file. + * @param bFromCache true if loading from the cache area. + * @return its success or failure. + */ bool LoadFromMsd( const RString &sPath, const MsdFile &msd, Course &out, bool bFromCache ); + /** + * @brief Attempt to load the course file from the buffer. + * @param sPath the path to the file. + * @param sBuffer the path to the buffer. + * @param out the course file. + * @return its success or failure. + */ bool LoadFromBuffer( const RString &sPath, const RString &sBuffer, Course &out ); + /** + * @brief Attempt to load an edit course from the hard drive. + * @param sEditFilePath a path on the hard drive to check. + * @param slot the Profile of the user with the edit course. + * @return its success or failure. + */ bool LoadEditFromFile( const RString &sEditFilePath, ProfileSlot slot ); + /** + * @brief Attempt to load an edit course from the buffer. + * @param sBuffer the path to the buffer. + * @param sPath the path to the file. + * @param slot the individual's profile. + * @return its success or failure. + */ bool LoadEditFromBuffer( const RString &sBuffer, const RString &sPath, ProfileSlot slot ); } #endif -/* - * (c) 2001-2004 Chris Danford +/** + * @file + * @author Chris Danford (c) 2001-2004 + * @section LICENSE * All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a diff --git a/src/CourseWriterCRS.cpp b/src/CourseWriterCRS.cpp index c69b405a7b..390fa45367 100644 --- a/src/CourseWriterCRS.cpp +++ b/src/CourseWriterCRS.cpp @@ -7,8 +7,14 @@ #include "Song.h" #include "RageFileDriverMemory.h" +/** @brief Load the difficulty names from CourseLoaderCRS. */ extern const char *g_CRSDifficultyNames[]; // in CourseLoaderCRS +/** + * @brief Get the string of the course difficulty. + * @param iVal the course difficulty. + * @return the string. + */ static RString DifficultyToCRSString( CourseDifficulty iVal ) { return g_CRSDifficultyNames[iVal]; diff --git a/src/CourseWriterCRS.h b/src/CourseWriterCRS.h index 3896e4ce99..9b2887c809 100644 --- a/src/CourseWriterCRS.h +++ b/src/CourseWriterCRS.h @@ -1,4 +1,4 @@ -/* CourseWriterCRS - Writes a Course to an .CRS file. */ +/** @brief CourseWriterCRS - Writes a Course to an .CRS file. */ #ifndef COURSE_WRITER_CRS_H #define COURSE_WRITER_CRS_H @@ -6,18 +6,44 @@ class Course; class RageFileBasic; +/** @brief The Course Writer handles writing the .crs files. */ namespace CourseWriterCRS { + /** + * @brief Write the course to a file. + * @param course the course contents. + * @param f the file being built. + * @param bSavingCache is true if cache information is being saved as well. + * @return its success or failure. + */ bool Write( const Course &course, RageFileBasic &f, bool bSavingCache ); + /** + * @brief Write the course to a file. + * @param course the course contents. + * @param sPath the path to the file. + * @param bSavingCache is true if cache information is being saved as well. + * @return its success or failure. + */ bool Write( const Course &course, const RString &sPath, bool bSavingCache ); + /** + * @brief Retrieve course information from a file for eventual writing. + * @param pCourse the course file. + * @param sOut the path to the file. + */ void GetEditFileContents( const Course *pCourse, RString &sOut ); + /** + * @brief Write the custom course to the machine's hard drive. + * @param pCourse the course file. + */ void WriteEditFileToMachine( const Course *pCourse ); } #endif -/* - * (c) 2001-2005 Chris Danford +/** + * @file + * @author Chris Danford (c) 2001-2005 + * @section LICENSE * All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a