Inline documentation added.

Author: NickyWeber

cocos2d/CCPackage+InstallData.h

@@ -8,17 +8,32 @@
 
 - (CCPackageInstallData *)installData;
 
-// Attaches install data to the package as an associated object
+/**
+ *  Attaches install data to the package as an associated object
+ *
+ *  @param installData The install data to be attached to the package
+ */
 - (void)setInstallData:(CCPackageInstallData *)installData;
 
-// Removes any install data attached to the package if there is any
+/**
+ *  Removes any install data attached to the package if there is any
+ */
 - (void)removeInstallData;
 
-// Reads values of dictionary and sets them on the install data
-// InstallData has to be attached to the package already
+/**
+ *  Reads values of dictionary and sets them on the install data.
+ *  Install data has to be attached to package already.
+ *
+ *  @param dictionary Dictionary containing values to populate the install data with
+ */
 - (void)populateInstallDataWithDictionary:(NSDictionary *)dictionary;
 
-// Returns a dictionary with the install data's values
+//
+/**
+ *  Writes the install data values into the provided dictionary.
+ *
+ *  @param dictionary Dictionary that shouöd be used to serialize the install data to
+ */
 - (void)writeInstallDataToDictionary:(NSMutableDictionary *)dictionary;
 
 @end

cocos2d/CCPackage+InstallData.m

@@ -22,6 +22,7 @@ - (CCPackageInstallData *)installData
 - (void)populateInstallDataWithDictionary:(NSDictionary *)dictionary
 {
     CCPackageInstallData *installData = [self installData];
+    NSAssert(installData != nil, @"Install data must not be nil");
 
     if (dictionary[PACKAGE_SERIALIZATION_KEY_LOCAL_DOWNLOAD_URL])
     {

cocos2d/CCPackage.h

@@ -5,29 +5,83 @@
 
 @interface CCPackage : NSObject
 
+/**
+ *  Name of the package
+ */
 @property (nonatomic, copy, readonly) NSString *name;
+
+/**
+ *  Resolution of the package, e.g. tablethd, phonehd, etc.
+ */
 @property (nonatomic, copy, readonly) NSString *resolution;
+
+/**
+ *  OS of the package e.g. iOS, Android, Mac
+ */
 @property (nonatomic, copy, readonly) NSString *os;
+
+/**
+ *  The remote URL of the package
+ */
 @property (nonatomic, copy, readonly) NSURL *remoteURL;
+
+/**
+ *  The local URL where the package is installed. This value will be initially nil and set only if installation was successful.
+ */
 @property (nonatomic, copy, readonly) NSURL *installURL;
+
+/**
+ *  The current status of the package
+ */
 @property (nonatomic, readonly) CCPackageStatus status;
 
+
+/**
+ *  Creates a new instance of a package.
+ *
+ *  @param name Name of the package
+ *  @param resolution Resolution of the package
+ *  @param os OS of the package
+ *  @param remoteURL Remote URL of the package
+ *
+ *  @return New instance of CCPackage
+ */
 - (instancetype)initWithName:(NSString *)name
                   resolution:(NSString *)resolution
                           os:(NSString *)os
                    remoteURL:(NSURL *)remoteURL;
 
-// Returns a new instance of a package populated with the contents of the dictionary
+/**
+ *  Creates a new instance of a package populated with the contents of the dictionary.
+ *  Used in context of serialization.
+ *
+ *  @param dictionary Dictionary containing values to populate the package with.
+ *
+ *  @return New instance of CCPackage
+ */
 - (instancetype)initWithDictionary:(NSDictionary *)dictionary;
 
-// Returns a dictionary containing the values of the package's properties.
+/**
+ *  Returns a dictionary containing the values of the package's properties.
+ *  Used in context of serialization.
+ *
+ *  @return A dictionary containing the values of the package
+ */
 - (NSDictionary *)toDictionary;
 
-// Returns an identifier of the package: The pattern is <NAME>-<OS>-<RESOLUTION>. Example: DLC-iOS-phonehd.
-// This name can vary though and can be determined by delegation.
+/**
+ *  Returns an identifier of the package: The pattern is <NAME>-<OS>-<RESOLUTION>. Example: DLC-iOS-phonehd.
+ *
+ *  @return A dictionary containing the values of the package
+ */
 - (NSString *)standardIdentifier;
 
-// Debug
+/**
+ *  Returns the status as a string.
+ *  Debugging purposes.
+ *
+ *  @return A string representation of the status property
+ */
 - (NSString *)statusToString;
 
 @end

cocos2d/CCPackageCocos2dEnabler.h

@@ -2,10 +2,23 @@
 
 @interface CCPackageCocos2dEnabler : NSObject
 
-// Enables packages by adding to cocos2d's search path and loading sprite sheets and filename lookups
+/**
+ *  Enables packages by adding to cocos2d's search path and loading sprite sheets and filename lookups.
+ *  Note: This method won't check a package's status and it is meant to be used for initialization
+ *  of packages on startup by the CCPackagesManager.
+ *
+ *  @param packages An array of CCPackage instance to be enabled
+ */
 - (void)enablePackages:(NSArray *)packages;
 
-// Disables packages by removing them fromcocos2d's search path after that reloading sprite sheets and filename lookups of remaining search paths.
+/**
+ *  Disables packages by removing them fromcocos2d's search path after that reloading sprite sheets and filename lookups
+ *  of remaining search paths.
+ *  Note: This method won't check a package's status and it is meant to be used for initialization
+ *  of packages on startup by the CCPackagesManager.
+ *
+ *  @param packages An array of CCPackage instance to be disabled
+ */
 - (void)disablePackages:(NSArray *)array;
 
 @end

cocos2d/CCPackageConstants.h

@@ -1,3 +1,4 @@
+// Errors
 extern NSUInteger const PACKAGE_ERROR_DOWNLOAD_SERVER_RESPONSE_NOT_OK;
 
 extern NSUInteger const PACKAGE_ERROR_INSTALL_PACKAGE_NOT_FOUND;
@@ -12,6 +13,8 @@ extern NSUInteger const PACKAGE_ERROR_MANAGER_CANNOT_ENABLE_NON_DISABLED_PACKAGE
 
 extern NSUInteger const PACKAGE_ERROR_MANAGER_CANNOT_DISABLE_NON_ENABLED_PACKAGE;
 
+
+// Misc
 extern NSString *const PACKAGE_REL_DOWNLOAD_FOLDER;
 
 extern NSString *const PACKAGE_REL_UNZIP_FOLDER;

cocos2d/CCPackageConstants.m

@@ -1,6 +1,7 @@
 #import <objc/NSObjCRuntime.h>
 #import <Foundation/Foundation.h>
 
+// Errors
 NSUInteger const PACKAGE_ERROR_DOWNLOAD_SERVER_RESPONSE_NOT_OK = 10000;
 
 NSUInteger const PACKAGE_ERROR_INSTALL_PACKAGE_NOT_FOUND = 10010;
@@ -15,6 +16,8 @@
 
 NSUInteger const PACKAGE_ERROR_MANAGER_CANNOT_DISABLE_NON_ENABLED_PACKAGE = 10021;
 
+
+// Misc
 NSString *const PACKAGE_REL_DOWNLOAD_FOLDER = @"com.cocos2d/Packages/Downloads";
 
 NSString *const PACKAGE_REL_UNZIP_FOLDER = @"com.cocos2d/Packages/Unzipped";

cocos2d/CCPackageDownload.h

@@ -6,27 +6,60 @@
 
 @interface CCPackageDownload : NSObject <NSURLConnectionDataDelegate>
 
-@property (nonatomic, copy) NSURL *packageURL;
-@property (nonatomic, copy) NSURL *localURL;
+/**
+ *  The URL of the package download, includes the filename
+ */
+@property (nonatomic, copy, readonly) NSURL *localURL;
+
+/**
+ *  The package being downloaded
+ */
 @property (nonatomic, strong, readonly) CCPackage *package;
 
+/**
+ *  Total bytes of the download. Might be 0 if no Content-Lenght header is sent by the
+ *  host.
+ */
 @property (nonatomic, readonly) NSUInteger totalBytes;
+
+/**
+ *  Bytes downloaded.
+ */
 @property (nonatomic, readonly) NSUInteger downloadedBytes;
 
+/**
+ * The delegate of the download.
+ */
 @property (nonatomic, weak) id <CCPackageDownloadDelegate> delegate;
 
+/**
+ *  Returns a new instance of a CCPackageDownload
+ *
+ *  @param package The package that should be downloaded
+ *  @param localURL The URL of the package download, includes the filename
+ *
+ *  @return A new instance of a CCPackageDownload
+ */
 - (instancetype)initWithPackage:(CCPackage *)package localURL:(NSURL *)localURL;
 
-// Starts the download, if there is a downloaded data the delegate is asked if the download should be resumed
+/**
+ *  Starts the download, if there is a downloaded data the delegate is asked if the download should be resumed
+ */
 - (void)start;
 
-// Stops the download and deletes the download file
+/**
+ *  Stops the download and deletes the download file
+ */
 - (void)cancel;
 
-// Stops the download
+/**
+ *  Stops the download
+ */
 - (void)pause;
 
-// Resumes a download, otherwise starts from the beginning
+/**
+ *  Resumes a download, otherwise starts from the beginning
+ */
 - (void)resume;
 
 @end

cocos2d/CCPackageDownload.m

@@ -12,6 +12,7 @@ @interface CCPackageDownload()
 @property (nonatomic, strong) NSURLConnection *connection;
 @property (nonatomic, strong, readwrite) CCPackage *package;
 @property (nonatomic, copy) NSString *tempPath;
+@property (nonatomic, copy, readwrite) NSURL *localURL;
 
 @property (nonatomic, readwrite) NSUInteger totalBytes;
 @property (nonatomic, readwrite) NSUInteger downloadedBytes;
@@ -31,7 +32,6 @@ - (instancetype)initWithPackage:(CCPackage *)package localURL:(NSURL *)localURL
     if (self)
     {
         self.package = package;
-        self.packageURL = package.remoteURL;
         self.localURL = localURL;
         self.fileSize = [self fileSizeOfDownload];
         self.tempPath = [[_localURL.path stringByDeletingLastPathComponent] stringByAppendingPathComponent:[self createTempName]];
@@ -83,7 +83,7 @@ - (void)resume
 
 - (NSString *)createTempName
 {
-    return [NSString stringWithFormat:@"%@_%@", [self sha1:[_packageURL absoluteString]], [_package standardIdentifier]];
+    return [NSString stringWithFormat:@"%@_%@", [self sha1:[_package.remoteURL absoluteString]], [_package standardIdentifier]];
 }
 
 - (NSString *)sha1:(NSString *)str
@@ -247,7 +247,7 @@ - (void)removeTempFile
 
 - (NSURLRequest *)createRequest
 {
-    NSMutableURLRequest *result = [NSMutableURLRequest requestWithURL:_packageURL];
+    NSMutableURLRequest *result = [NSMutableURLRequest requestWithURL:_package.remoteURL];
 
     if ([_delegate respondsToSelector:@selector(request:ofDownload:)])
     {
@@ -465,7 +465,7 @@ - (void)closeConnectionAndFileHandle
 
 - (NSString *)description
 {
-    return [NSString stringWithFormat:@"PACKAGE URL: %@, LOCAL URL: %@", _packageURL, _localURL];
+    return [NSString stringWithFormat:@"PACKAGE URL: %@, LOCAL URL: %@", _package.remoteURL, _localURL];
 }
 
 @end

cocos2d/CCPackageDownloadDelegate.h

@@ -5,29 +5,63 @@
 @protocol CCPackageDownloadDelegate <NSObject>
 
 @required
-// Called when the http request finishes
+
+/**
+ *  Called when the http request finishes successfully
+ *
+ *  @param download The download object that finished
+ */
 - (void)downloadFinished:(CCPackageDownload *)download;
 
-// Called when the http request fails, for example a timeout, not a 404 returned.
+/**
+ *  Called when the http request fails, for example a timeout, not a 404 returned.
+ *
+ *  @param download The download object that failed
+ *  @param error Error pointer to an error object containing details
+ */
 - (void)downloadFailed:(CCPackageDownload *)download error:(NSError *)error;
 
+
 @optional
-// Called whenever new bytes are received from the host.
-// Returns the bytes downloaded and the total bytes.
-// Total bytes can be 0 throughout a download if the response does not contain a Content-Length header.
+
+/**
+ *  Called whenever new bytes are received from the host.
+ *
+ *  @param download The download object that reported progress
+ *  @param downloadedBytes bytes downloaded
+ *  @param totalBytes Total bytes downloaded. Total bytes can be 0 throughout a download if the response does not contain a Content-Length header.
+ */
 - (void)downlowdProgress:(CCPackageDownload *)download downloadedBytes:(NSUInteger)downloadedBytes totalBytes:(NSUInteger)totalBytes;
 
-// Return YES if a partial download should be resume if the host accepts range requests otherwise it will start over
-// Return NO if the download should start over
-// This method will only be invoked if there is a downloaded file
-// If not implemented the default is as if returned YES
+
+/**
+ *  Return YES if a download should be resumed. If not implemented YES is default.
+ *  Return NO if the download should start over.
+ *  This method will only be invoked if there is a downloaded file
+ *
+ *  @param download The download object that should be resumed
+ *
+ *  @return whether a download should be resumed(YES) or started over(NO)
+ */
 - (BOOL)shouldResumeDownload:(CCPackageDownload *)download;
 
-// Return whether a completed download with the same filename should be overwritten.
+/**
+ *  Return whether a completed download with the same filename should be overwritten.
+ *  If not implemented default is NO.
+ *
+ *  @param download The download object which downloaded file should be overwritten.
+ *
+ *  @return whether an already downloaded file should be overwritten(YES) or started over(NO)
+ */
 - (BOOL)shouldOverwriteDownloadedFile:(CCPackageDownload *)download;
 
-// Provides the request before it is sent to let delegate adjust headers etc.
-// If there is a partial download which should be resumed a Range header will be set after this invocation.
+/**
+ *  Provides the request before it is sent to let delegate adjust headers etc.
+ *  If there is a partial download which should be resumed a Range header will be set after this invocation.
+ *
+ *  @param request The request object that will be used for the download
+ *  @param download The download object which will start with the given request
+ */
 - (void)request:(NSMutableURLRequest *)request ofDownload:(CCPackageDownload *)download;
 
 @end