From c19985fc7e094f4ece1b64e8688a6b5e95f16c16 Mon Sep 17 00:00:00 2001 From: Anna Schumaker Date: Mon, 20 Oct 2014 21:38:16 -0400 Subject: [PATCH] tags: Add doxygen documentation Signed-off-by: Anna Schumaker --- core/tags.cpp | 3 +- include/core/tags.h | 227 +++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 228 insertions(+), 2 deletions(-) diff --git a/core/tags.cpp b/core/tags.cpp index 3cae17aa..656f529d 100644 --- a/core/tags.cpp +++ b/core/tags.cpp @@ -1,4 +1,5 @@ -/* +/** + * @file * Copyright 2014 (c) Anna Schumaker. */ diff --git a/include/core/tags.h b/include/core/tags.h index 03bd91b7..5af9a32a 100644 --- a/include/core/tags.h +++ b/include/core/tags.h @@ -1,4 +1,5 @@ -/* +/** + * @file * Copyright 2014 (c) Anna Schumaker. */ #ifndef OCARINA_CORE_TAGS_H @@ -7,69 +8,188 @@ #include +/** + * Track fields that can be compared. + */ enum sort_t { + /** Artist name */ SORT_ARTIST, + /** Album name */ SORT_ALBUM, + /** Play count */ SORT_COUNT, + /** Genre */ SORT_GENRE, + /** Track length */ SORT_LENGTH, + /** Date the track was last played */ SORT_PLAYED, + /** Track title */ SORT_TITLE, + /** Track number */ SORT_TRACK, + /** Track year */ SORT_YEAR, }; +/** + * Artist tag + */ class Artist : public DatabaseEntry { public: + /** Artist name */ std::string name; + /** Artist name (lowercase) */ std::string lower; + /** Artist tag constructor */ Artist(); + + /** + * Artist tag constructor + * @param name Artist name + */ Artist(const std::string &); + + /** + * Called to access the artist tag's primary key + * @return Artist::name + */ const std::string primary_key() const; + + /** + * Read artist information from file. + * @param file The file to read from. + */ void read(File &); + + /** + * Write artist information to file. + * @param file The file to write to. + */ void write(File &); }; +/** + * Album tag + */ class Album : public DatabaseEntry { public: + /** Album name */ std::string name; + /** Album name (lowercase) */ std::string lower; + /** Album year */ unsigned int year; + /** Album tag constructor */ Album(); + + /** + * Album tag constructor + * @param name Album name + * @param year Album year + */ Album(const std::string &, unsigned int); + + /** + * Called to access the artist tag's primary key + * @return "Album::year"."Album::name" (Example: 1968.White Album) + */ const std::string primary_key() const; + + /** + * Read album information from file. + * @param file The file to read from. + */ void read(File &); + + /** + * Write album information to file. + * @param file The file to write to. + */ void write(File &); }; +/** + * Genre tag + */ class Genre : public DatabaseEntry { public: + /** Genre name */ std::string name; + /** Genre name (lowercase) */ std::string lower; + /** Genre tag constructor */ Genre(); + + /** + * Genre tag constructor + * @param name Genre name + */ Genre(const std::string &); + + /** + * Called to access the artist tag's primary key + * @return Genre::name + */ const std::string primary_key() const; + + /** + * Read genre information from file. + * @param file The file to read from. + */ void read(File &); + + /** + * Write genre information to file. + * @param file The file to write to. + */ void write(File &); }; +/** + * Library tag + */ class Library : public DatabaseEntry { public: + /** Path to the directory containing this library's audio files */ std::string root_path; + /** Number of tracks in this library */ unsigned int count; + /** True if the library is enabled, false otherwise */ bool enabled; + /** Library constructor */ Library(); + + /** + * Library constructor + * @param path Path to the library on disk. + */ Library(const std::string &); + + /** + * Called to access the library tag's primary key. + * @return Library::root_path + */ const std::string primary_key() const; + + /** + * Read library information from file. + * @param file The file to read from. + */ void read(File &); + + /** + * Write library information to file. + * @param file The file to write to. + */ void write(File &); }; @@ -79,51 +199,156 @@ private: void set_length_str(); public: + /** Pointer to the library containing this track */ Library *library; + /** Pointer to this track's artist information */ Artist *artist; + /** Pointer to this track's album information */ Album *album; + /** Pointer to this track's genre information */ Genre *genre; + /** Track number of this track */ unsigned int track; + /** Length of this track (in seconds) */ unsigned int length; + /** The number of times this track has been played */ unsigned int play_count; + /** The year this track was last played */ unsigned int last_year; + /** The month this track was last played */ unsigned int last_month; + /** The day this track was last played */ unsigned int last_day; + /** The title of this track */ std :: string title; + /** The title of this track (in lowercase) */ std :: string title_lower; + /** The filepath of this track, relative to the library root */ std :: string filepath; + /** The length of this track in a human readable string */ std :: string length_str; + /** Track constructor */ Track(); + + /** + * Track constructor + * @param filepath Filepath of the track + * @param library Library containing the track + */ Track(const std::string &, Library *); + + /** Track destructor */ ~Track(); + + /** + * Called to access a track's primary key + * @return The full path of the track + */ const std::string primary_key() const; + + /** + * 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 + */ void write(File &); + + /** + * Read the tags associated with this track + * @return True on success + */ bool tag(); + + /** @return The full path of this track */ const std::string path() const; + + /** Increments play count and sets date-last-played information. */ void played(); + + /** + * Compare two tracks based on a specific field. + * @param rhs The other track to compare. + * @param field The field to compare. + * @return 0 if lhs == rhs + * @return < 0 if lhs < rhs, or rhs is NULL + * @return > 0 if lhs > rhs + */ int less_than(Track *, sort_t); }; +/** Functions for accessing the tag database */ namespace tagdb { + /** Load tag databases from disk */ void init(); + /** Write track database to disk */ void commit(); + /** Write library database to disk */ void commit_library(); + + /** + * Add a track to the database + * @param filepath Filepath to be added + * @param library Library containing the new track + * @return A pointer to the newly created track + */ Track *add_track(const std::string &, Library *); + + /** + * Add a new library to the database + * @param filepath Path of the directory to be added + * @return A pointer to the newly created library + */ Library *add_library(const std::string &); + + /** + * Remove a track from the database + * @param track_id The index of the track in the database. + */ void remove_track(unsigned int); + + /** + * Remove a library from the database. + * @param library_id The index of the library in the database. + */ void remove_library(unsigned int); + + /** + * Find a track based on track_id + * @param track_id Track id to look up + * @return A pointer to the found track, or NULL + */ Track *lookup(unsigned int); + + /** + * Find a library based on library_id + * @param library_id The library id to look up + * @return A pointer to the found library, or NULL + */ Library *lookup_library(unsigned int); + + /** + * Call to access the track database + * @return The track database + */ Database &get_track_db(); + + /** + * Call to access the library database + * @return The library database + */ Database &get_library_db(); }