Permalink
Browse files

Doxygen

  • Loading branch information...
1 parent 46cb7d8 commit 2b3ac5bfcb8ebe9c511624dfaa62a68e89d9a77d @Keytwo Keytwo committed May 20, 2011
View
@@ -0,0 +1,22 @@
+CREATE_SUBDIRS = YES
+ALPHABETICAL_INDEX = YES
+COLS_IN_ALPHA_INDEX = 3
+GENERATE_HTML = YES
+EXCLUDE_PATTERNS = **/.git **/test **/target **/.settings **/resources **/com/twmacinta
+FILE_PATTERNS = *.java
+INPUT = audiobox.fm-core/src/main/java/fm audiobox.fm-sync/src/main/java/fm
+PROJECT_NAME = AudioBox.fm Java Libs
+PROJECT_NUMBER = 2.0-SNAPSHOT
+RECURSIVE = YES
+OUTPUT_DIRECTORY = target
+JAVADOC_AUTOBRIEF = YES
+OPTIMIZE_OUTPUT_JAVA = YES
+EXTRACT_ALL = YES
+GENERATE_TODOLIST = YES
+QUIET = YES
+WARNINGS = NO
+WARN_IF_UNDOCUMENTED = YES
+WARN_IF_DOC_ERROR = YES
+WARN_NO_PARAMDOC = YES
+WARN_LOGFILE = target/doxygen.log
+
@@ -28,6 +28,7 @@
import java.io.Serializable;
import java.util.ArrayList;
import java.util.List;
+import java.util.Observer;
import java.util.zip.GZIPInputStream;
import org.apache.http.Header;
@@ -67,17 +68,20 @@
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
+import fm.audiobox.configurations.DefaultConfiguration;
+import fm.audiobox.configurations.DefaultFactory;
import fm.audiobox.core.exceptions.LoginException;
import fm.audiobox.core.exceptions.ServiceException;
+import fm.audiobox.core.models.AbstractCollectionEntity;
import fm.audiobox.core.models.User;
import fm.audiobox.interfaces.IConfiguration;
import fm.audiobox.interfaces.IConnector;
import fm.audiobox.interfaces.IEntity;
+import fm.audiobox.interfaces.IFactory;
/**
* AudioBox is the main library class. Every request to AudioBox.fm should pass through this object.
- * This class is used mainly to configure every aspect of the library itself.<br/>
* To populate and get informations about user library use the {@link User} (or an extended User) model instead.
* <p>
*
@@ -91,29 +95,32 @@
*
* <p>
*
- * In order to make AudioBox load your extended models you will need to provide your {@link Model} extension
- * through the {@link AudioBox#setCollectionListenerFor(String, CollectionListener)} method.<br/>
+ * In order to make AudioBox load your extended models you will need to provide your {@link AbstractEntity} extension
+ * through an {@link IFactory#setEntity(String, Class)} implementation. If you don't want to implement one you can use
+ * the {@link DefaultFactory}.<br/>
*
* <p>
*
- * Note that some of the requests, such as the ModelsCollection population requests, can be done asynchronously.<br/>
- * To keep track of the collection building process you can make use of the {@link CollectionListener} object.
+ * Note that some of the requests, such as the {@link AbstractCollectionEntity} population requests, can be done
+ * asynchronously.<br/>
+ * To keep track of the collection building process you can use {@link Observer Observers}.
*
* <p>
*
* The usual execution flow can be demonstrated by the code snippet below:
*
* <pre>
+ * @code
+ * // With this object you can configure many aspects of the libs
+ * IConfiguration configuration = new DefaultConfiguration("My test application");
+ *
* // Creating the new AudioBox instance
- * abc = new AudioBox();
+ * abc = new AudioBox(configuration);
*
* // If you extended the {@link User} model AudioBox should
* // be informed before the login take place.
- * AudioBox.setModelClassFor(AudioBox.USER_KEY , MyUser.class );
+ * abc.getConfiguration().getFactory().setEntity(User.TAGNAME, MyUser.class);
*
- * // Suppose we want to limit requests timeout to 5 seconds
- * abc.getMainConnector().setTimeout( 5000 );
- *
* // Now we can try to perform a login...
* try {
*
@@ -124,12 +131,18 @@
* // To browse user library we have some nice utils methods
* // We can get the user's playlists...
* Playlists pls = user.getPlaylists();
+ * // This object is still empty because you may want to add some observer to it or do
+ * // something else with it.
+ *
+ * // To populate the playlists call load method:
+ * pls.load(false);
*
* // ...and get more details on a specific one
* Playlist pl = playlists.get(0);
*
* // Get playlist's tracks
* Tracks trs = pl.getTracks();
+ * trs.load(false);
*
* // Track informations
* Track tr = trs.get(0);
@@ -139,14 +152,15 @@
* } catch (ServiceException e) {
* // Handle {@link ServiceException}
* }
+ * @endcode
* </pre>
*
* This is briefly the navigation loop. Moreover each model offer some action that can be performed. To know what a model
* can do consult the specific model documentation.
*
* @author Valerio Chiodino
* @author Fabio Tunno
- * @version 0.0.1
+ * @version 1.0.0
*/
public class AudioBox {
@@ -39,8 +39,7 @@
* Album XML looks like this:
*
* <pre>
- * {@code
- *
+ * @code
* <album>
* <name>Album name</name>
* <token>coq8FfgK</token>
@@ -54,7 +53,7 @@
* <token>fs8d8g9d</token>
* </artist>
* </album>
- * }
+ * @endcode
* </pre>
*
* @author Valerio Chiodino
@@ -39,12 +39,12 @@
* Artist XML looks like this:
*
* <pre>
- * {@code
+ * @code
* <artist>
* <name>Artist name</name>
* <token>cd8sa09df</token>
* </artist>
- * }
+ * @endcode
* </pre>
*
* @author Valerio Chiodino
@@ -39,13 +39,13 @@
* CoverUrls XML looks like this:
*
* <pre>
- * {@code
- * <covers>
- * <l>http://media.audiobox.fm/images/albums/HOBh1lMt/l.jpg?1277867432</l>
- * <m>http://media.audiobox.fm/images/albums/HOBh1lMt/m.jpg?1277867432</m>
- * <s>http://media.audiobox.fm/images/albums/HOBh1lMt/s.jpg?1277867432</s>
- * </covers>
- * }
+ * @code
+ * <covers>
+ * <l>http://media.audiobox.fm/images/albums/HOBh1lMt/l.jpg?1277867432</l>
+ * <m>http://media.audiobox.fm/images/albums/HOBh1lMt/m.jpg?1277867432</m>
+ * <s>http://media.audiobox.fm/images/albums/HOBh1lMt/s.jpg?1277867432</s>
+ * </covers>
+ * @endcode
* </pre>
*
* @author Valerio Chiodino
@@ -39,12 +39,12 @@
* Error XML looks like this:
*
* <pre>
- * {@code
+ * @code
* <error>
* <status>500</name>
* <message>This is an error message</token>
* </error>
- * }
+ * @endcode
* </pre>
*
* @author Valerio Chiodino
@@ -39,12 +39,12 @@
* Genre XML looks like this:
*
* <pre>
- * {@code
+ * @code
* <genre>
* <name>Genre name</name>
* <token>sjKzpds9Tk</token>
* </genre>
- * }
+ * @endcode
* </pre>
*
* @author Valerio Chiodino
@@ -38,20 +38,20 @@
* Plan XML looks like this:
*
* <pre>
- * {@code
- <plan>
- <feat_api>true</feat_api>
- <feat_cloud_web_player>true</feat_cloud_web_player>
- <feat_dropbox>true</feat_dropbox>
- <feat_gigjunkie>true</feat_gigjunkie>
- <feat_lastfm>true</feat_lastfm>
- <feat_manager>true</feat_manager>
- <feat_multiformat>true</feat_multiformat>
- <feat_social_networks>true</feat_social_networks>
- <feat_youtube_channel>true</feat_youtube_channel>
- <name>plan</name>
- </plan>
- * }
+ * @code
+ * <plan>
+ * <feat_api>true</feat_api>
+ * <feat_cloud_web_player>true</feat_cloud_web_player>
+ * <feat_dropbox>true</feat_dropbox>
+ * <feat_gigjunkie>true</feat_gigjunkie>
+ * <feat_lastfm>true</feat_lastfm>
+ * <feat_manager>true</feat_manager>
+ * <feat_multiformat>true</feat_multiformat>
+ * <feat_social_networks>true</feat_social_networks>
+ * <feat_youtube_channel>true</feat_youtube_channel>
+ * <name>plan</name>
+ * </plan>
+ * @endcode
* </pre>
*
* @author Valerio Chiodino
@@ -59,15 +59,15 @@
* Profile XML looks like this:
*
* <pre>
- * {@code
+ * @code
* <playlist>
* <token>as89d7h4sa</token>
* <name>Music</name>
* <position>1</position>
* <playlist_type>audio</playlist_type>
* <playlist_tracks_count>12312</playlist_tracks_count>
* </playlist>
- * }
+ * @endcode
* </pre>
*
* @author Valerio Chiodino
@@ -39,12 +39,12 @@
* Profile XML looks like this:
*
* <pre>
- * {@code
- <profile>
- <autoplay>false</autoplay>
- <real_name>Name Surname</real_name>
- </profile>
- * }
+ * @code
+ * <profile>
+ * <autoplay>false</autoplay>
+ * <real_name>Name Surname</real_name>
+ * </profile>
+ * @endcode
* </pre>
*
* @author Valerio Chiodino
@@ -46,7 +46,7 @@
* The XML response looks like this:
*
* <pre>
- * {@code
+ * @code
* <track>
* <token>{token}</token>
* <title>Title</title>
@@ -64,7 +64,7 @@
* <artist>...</artist>
* <genre>...</genre>
* </track>
- * }
+ * @endcode
* </pre>
*
* @author Valerio Chiodino
@@ -43,23 +43,22 @@
* When a login is successfully performed an XML like the following is received and parsed:
*
* <pre>
- * {@code
- *
- <user>
- <bytes_served>25352551153</bytes_served>
- <email>user@domain.com</email>
- <play_count>3378</play_count>
- <quota>1318739344</quota>
- <tracks_count>273</tracks_count>
- <username>username</username>
- <available_storage>162135015424</available_storage>
- <allowed_formats>aac;mp3;mp2;m4a;m4b;m4r;mp4;3gp;ogg;oga;flac;spx;wma;rm;ram;wav;mpc;mp+;mpp;aiff;aif;aifc;tta</allowed_formats>
- <time_zone>Rome</time_zone>
- <trial_ends_at>2011-03-05 08:20:38 +0100</trial_ends_at>
- <profile>....</profile>
- <plan>...</plan>
- </user>
- * }
+ * @code
+ * <user>
+ * <bytes_served>25352551153</bytes_served>
+ * <email>user@domain.com</email>
+ * <play_count>3378</play_count>
+ * <quota>1318739344</quota>
+ * <tracks_count>273</tracks_count>
+ * <username>username</username>
+ * <available_storage>162135015424</available_storage>
+ * <allowed_formats>aac;mp3;mp2;m4a;m4b;m4r;mp4;3gp;ogg;oga;flac;spx;wma;rm;ram;wav;mpc;mp+;mpp;aiff;aif;aifc;tta</allowed_formats>
+ * <time_zone>Rome</time_zone>
+ * <trial_ends_at>2011-03-05 08:20:38 +0100</trial_ends_at>
+ * <profile>....</profile>
+ * <plan>...</plan>
+ * </user>
+ * @endcode
* </pre>
*
* Through the User object you have access to its library that can be browsed by:
@@ -34,6 +34,8 @@
import fm.audiobox.interfaces.IConnector.IConnectionMethod;
/**
+ * This interface describes how an implementation of the AudioBox configuration should behave.<br/>
+ * An implementing class is mainly used to configure every aspect of the library itself.
*
* @author Fabio Tunno
*/
@@ -16,15 +16,17 @@
/**
* Sets the right entity associated with its default class
- * @param klass default {@link Class}
- * @param entity new {@link Class} to be instantiated
+ *
+ * @param tagName the name of the tag to associate to the class
+ * @param entityClass new {@link Class} to be instantiated
*/
- public void setEntity(String tagName, Class<? extends IEntity> entity);
+ public void setEntity(String tagName, Class<? extends IEntity> entityClass);
/**
* Returns true if an {@link IEntity} has been set
*
* @param tagName the {@link IEntity} tag name
+ *
* @return true if an {@link IEntity} has been set
*/
public boolean containsEntity(String tagName);
View
@@ -1,20 +0,0 @@
-ALPHABETICAL_INDEX=YES
-COLS_IN_ALPHA_INDEX=3
-GENERATE_HTML=YES
-EXCLUDE_PATTERNS=**/.git **/test **/target **/.settings **/resources **/com/twmacinta
-FILE_PATTERNS=*.java
-
-INPUT=audiobox.fm-core/src/main/java/fm audiobox.fm-sync/src/main/java/fm
-
-PROJECT_NAME=AudioBox.fm Java Libs
-PROJECT_NUMBER=2.0-SNAPSHOT
-RECURSIVE=YES
-
-OUTPUT_DIRECTORY=target
-
-JAVADOC_AUTOBRIEF=YES
-OPTIMIZE_OUTPUT_JAVA=YES
-EXTRACT_ALL=YES
-
-
-

0 comments on commit 2b3ac5b

Please sign in to comment.