From 30b2ba0fffc1be08e92154a028faf3ab2dc3fd7e Mon Sep 17 00:00:00 2001 From: Anna Schumaker Date: Thu, 4 Dec 2014 08:29:17 -0500 Subject: [PATCH] Track: Doxygen documentation updates This patch fixes up formatting a little bit and removes the Track section of the DESIGN document. Signed-off-by: Anna Schumaker --- DESIGN | 118 ++++---------------------------------- core/tags/track.cpp | 26 ++++----- include/core/tags/track.h | 23 ++++---- 3 files changed, 37 insertions(+), 130 deletions(-) diff --git a/DESIGN b/DESIGN index 0982dc75..2e902e4f 100644 --- a/DESIGN +++ b/DESIGN @@ -66,9 +66,17 @@ Callbacks: -Track Tag: - The track tag is used to store information about a single track in the - user's music collection. +Queue: + Queues are lists of songs that the user has requested to play. They + are the main interface for all music played by Ocarina. + +- Flags: + enum queue_flag { + Q_ENABLED (1 << 0), + Q_RANDOM (1 << 1), + Q_REPEAT (1 << 2), + Q_NO_SORT (1 << 3), + }; - Sorting: enum sort_t { @@ -83,110 +91,6 @@ Track Tag: SORT_YEAR, }; -- Track: - class Track : public DatabaseEntry { - public: - Library *library; - Artist *artist; - Album *album; - Genre *genre; - - unsigned int track; - unsigned int length; - unsigned int play_count; - unsigned int last_year; - unsigned int last_month; - unsigned int last_day; - - std :: string title; - std :: string title_lower; - std :: string filepath; - std :: string length_str; - - Track(); - Track(const std::string &, Library *); - const std::string primary_key() const; - void read(File &); - void write(File &); - - bool tag(); - const std::string path(); - void played(); - bool less_than(Track *, sort_t); - }; - -- File Format: - File << library->id << artist->id << album->id << genre->id << track; - File << last_year << last_month << last_day << play_count << length; - File << title << endl; - File << filepath << endl; - -- API: - Track(); - Initialize an invalid Track instance. - - Track(const std::string &full_path, Library *lib); - This function will only set up the primary key, and the tag() - function must be called to find audio tags. - - - Strip library path from the beginning of full_path and use - the result to set filepath. - - Set library = lib. - - const std::string Track :: primary_key() const; - return path(); - - void read(File &f); - Read track information from file. Look up the corresponding - Library, Artist, Album and Genre pointers. Add title to the - filter and find the string version of length. - - void write(File &f); - Write track information to file. - - bool Track :: tag(); - Use TagLib to find tags and audio properties for this file. - - - Insert Artist, Album, and Genre into their databases and - set the corresponding pointers. - - Find title, track number, and length. - - Set play_count, last_year, last_month and last_day = 0. - - Set lowercase title and find the string form of length. - - Return true if the track could be tagged and false otherwise. - - const std::string Track :: path(); - Combine library->path and filepath to find the full path to - the audio file. - - void Track :: played(); - Called when a track has been played. Increment the play count - and set last_day, last_month, and last_year to today's date. - - Call tagdb :: commit() to save the track database. - - int Track :: less_than(Track *rhs, sort_t field); - Compare the requested field for this Track instance to the same - field in the provided track. - - Return -1 if this < rhs. - Return 0 if this == rhs. - Return 1 if this > rhs. - - - -Queue: - Queues are lists of songs that the user has requested to play. They - are the main interface for all music played by Ocarina. - -- Flags: - enum queue_flag { - Q_ENABLED (1 << 0), - Q_RANDOM (1 << 1), - Q_REPEAT (1 << 2), - Q_NO_SORT (1 << 3), - }; - - Sort info: struct sort_info { sort_t field; diff --git a/core/tags/track.cpp b/core/tags/track.cpp index b52e61b8..826f416a 100644 --- a/core/tags/track.cpp +++ b/core/tags/track.cpp @@ -123,16 +123,16 @@ int Track :: compare_date(const Track *rhs) return ret; } -void Track :: read(File &f) +void Track :: read(File &file) { unsigned int library_id, artist_id, album_id, genre_id; - f >> library_id >> artist_id >> album_id >> genre_id; - f >> _track >> _date.year >> _date.month >> _date.day; - f >> _count >> _length; + file >> library_id >> artist_id >> album_id >> genre_id; + file >> _track >> _date.year >> _date.month >> _date.day; + file >> _count >> _length; - GenericTag :: read(f); - _path = f.getline(); + GenericTag :: read(file); + _path = file.getline(); _library = tags :: get_library(library_id); _artist = tags :: get_artist(artist_id); @@ -145,14 +145,14 @@ void Track :: read(File &f) _library->inc_size(); } -void Track :: write(File &f) +void Track :: write(File &file) { - f << _library->index() << " " << _artist->index() << " "; - f << _album->index() << " " << _genre->index() << " " << _track << " "; - f << _date.year << " " << _date.month << " " << _date.day << " "; - f << _count << " " << _length << " "; - GenericTag :: write(f); - f << std::endl << _path << std::endl; + file << _library->index() << " " << _artist->index() << " "; + file << _album->index() << " " << _genre->index() << " " << _track << " "; + file << _date.year << " " << _date.month << " " << _date.day << " "; + file << _count << " " << _length << " "; + GenericTag :: write(file); + file << std::endl << _path << std::endl; } diff --git a/include/core/tags/track.h b/include/core/tags/track.h index 3a189017..1939826e 100644 --- a/include/core/tags/track.h +++ b/include/core/tags/track.h @@ -21,6 +21,10 @@ struct date { }; +/** + * The Track tag is used to store information about tracks that + * have been added to the tag database. + */ class Track : public GenericTag { private: Album *_album; /**< Pointer to the Album containing this track. */ @@ -36,9 +40,6 @@ private: std::string _path; /**< Path of this track, relative to the Library. */ public: - /** Track constructor */ - Track(); - /** * Track constructor * @@ -61,8 +62,8 @@ public: */ Track(const Track &); - /** Track destructor */ - ~Track(); + Track(); /**< Track constructor. */ + ~Track(); /**< Track destructor. */ Album *album(); /**< @return Track::_album. */ @@ -92,7 +93,7 @@ public: * A track's primary key is the concatenation of the library index * and the relative path. * - * @return "Track::_library::index()"/Track::_path + * @return Track::_library->index() / Track::_path. */ const std::string primary_key() const; @@ -111,14 +112,16 @@ public: /** - * Read track data from file - * @param file The file to read from + * Read track data from file. + * + * @param file The file to read from. */ void read(File &); /** - * Write track data to file - * @param file The file to write to + * Write track data to file. + * + * @param file The file to write to. */ void write(File &); };