Merge pull request #31 from cloudspace/67859548_update_model_comments

67859548 update model comments

Author: jeremiahishere

EasyReader.xcodeproj/project.pbxproj

@@ -578,14 +578,14 @@
 		9DAC171D170A043200383722 /* Models */ = {
 			isa = PBXGroup;
 			children = (
+				8E7F81EE18D0BF8500BC50C2 /* CSBaseObject.h */,
+				8E7F81EF18D0BF8500BC50C2 /* CSBaseObject.m */,
 				0DE51FF618CF919900454E51 /* Feed.h */,
 				0DE51FF718CF919900454E51 /* Feed.m */,
 				0DE51FEF18CF911000454E51 /* FeedItem.h */,
 				0DE51FF018CF911000454E51 /* FeedItem.m */,
 				0DE51FF118CF911000454E51 /* User.h */,
 				0DE51FF218CF911000454E51 /* User.m */,
-				8E7F81EE18D0BF8500BC50C2 /* CSBaseObject.h */,
-				8E7F81EF18D0BF8500BC50C2 /* CSBaseObject.m */,
 			);
 			path = Models;
 			sourceTree = "<group>";

EasyReader/Application/Models/CSBaseObject.h

@@ -11,7 +11,23 @@
 #import "NSObject+CSNilAdditions.h"
 #import "NSString+Inflections.h"
 
+
+#pragma mark - CSBaseObject -
+
+/**
+ * A base for NSManagedObjects that represent objects in a remote API object
+ */
 @interface CSBaseObject : NSManagedObject
+
+
+#pragma mark - Instance creation from API Data helpers
+
+/*
+ * Creates or updates an object base on API data
+ *
+ * @param remoteObjectData the api data to update/create based on
+ */
 + (id)createOrUpdateFirstFromAPIData:(NSDictionary *)remoteObjectData;
 
+
 @end

EasyReader/Application/Models/Feed.h

@@ -12,32 +12,78 @@
 
 @class FeedItem, User;
 
+
+#pragma mark - Feed -
+
+/**
+ * An RSS Feed
+ */
 @interface Feed : CSBaseObject
 
+
+#pragma mark  - Core Data Properties
+
+/// This feed's icon
 @property (nonatomic, retain) NSString * icon;
+
+/// This feed's name
 @property (nonatomic, retain) NSString * name;
+
+/// This feed's RSS url
 @property (nonatomic, retain) NSString * url;
+
+/// The remote ID of this feed object on the API
 @property (nonatomic, retain) NSNumber * id;
+
+/// The user this feed is associated to
 @property (nonatomic, retain) User *user;
+
+/// The items in this feed
 @property (nonatomic, retain) NSSet *feedItems;
-@end
 
-@interface Feed (CoreDataGeneratedAccessors)
 
-- (void)addFeedItemsObject:(FeedItem *)value;
-- (void)removeFeedItemsObject:(FeedItem *)value;
-- (void)addFeedItems:(NSSet *)values;
-- (void)removeFeedItems:(NSSet *)values;
+#pragma mark - API Methods
 
+/**
+ * Creates a new feed based on a given url
+ *
+ * @param url
+ * @param successBlock A block to be run on API call success
+ * @param failureBlock A block to be run on API call failure
+ */
 + (void) createFeedWithUrl:(NSString *) url
                    success:(void(^)(NSDictionary *data))successBlock
                    failure:(void(^)(NSDictionary *data))failureBlock;
 
+/**
+ * Requests the default feeds list (called once on the first app run)
+ *
+ * @param successBlock A block to be run on API call success
+ * @param failureBlock A block to be run on API call failure
+ */
 + (void) requestDefaultFeedsWithSuccess:(void(^)(NSDictionary *data))successBlock
                                 failure:(void(^)(NSDictionary *data))failureBlock;
 
+/**
+ * Requests a list of feeds by name (search)
+ *
+ * @param successBlock A block to be run on API call success
+ * @param failureBlock A block to be run on API call failure
+ */
 + (void) requestFeedsByName:(NSString *) name
                     success:(void(^)(NSDictionary *data))successBlock
                     failure:(void(^)(NSDictionary *data))failureBlock;
 
 @end
+
+
+#pragma mark - Core Data Generated Accessors -
+
+@interface Feed (CoreDataGeneratedAccessors)
+
+- (void)addFeedItemsObject:(FeedItem *)value;
+- (void)removeFeedItemsObject:(FeedItem *)value;
+- (void)addFeedItems:(NSSet *)values;
+- (void)removeFeedItems:(NSSet *)values;
+
+@end

EasyReader/Application/Models/FeedItem.h

@@ -12,23 +12,65 @@
 
 @class Feed;
 
+
+#pragma mark - FeedItem -
+
+/**
+ * A single feed item in a feed
+ */
 @interface FeedItem : CSBaseObject
 
+
+#pragma mark - Core Data Properties
+
+/// The article title for this feed item
 @property (nonatomic, retain) NSString * title;
+
+/// The summary for this feed item
 @property (nonatomic, retain) NSString * summary;
+
+/// The time this feed item was updated
 @property (nonatomic, retain) NSDate * updatedAt;
+
+/// The time this feed item's article was published
 @property (nonatomic, retain) NSDate * publishedAt;
+
+/// The time this feed item was created
 @property (nonatomic, retain) NSDate * createdAt;
+
+/// The image for this feed item
 @property (nonatomic, retain) NSString * image;
+
+/// The article URL for this feed item
 @property (nonatomic, retain) NSString * url;
+
+/// This feed items remote API id
 @property (nonatomic, retain) NSNumber * id;
+
+/// The feed this item is in
 @property (nonatomic, retain) Feed *feed;
 
-- (NSString *)headline;
 
+#pragma mark - Properties
+
+/// The appropriate headline for this article
+@property (readonly) NSString *headline;
+
+
+#pragma mark - API methods
+
+/**
+ * Requests new feed items from a group of feeds
+ *
+ * @param feeds
+ * @param startAt
+ * @param success A block to be run on API call success
+ * @param failure A block to be run on API call failure
+ */
 + (void) requestFeedItemsFromFeeds:(NSSet *)feeds
                              Since:(NSDate *)startAt
                            success:(void(^)(NSDictionary *data))successBlock
                            failure:(void(^)(NSDictionary *data))failureBlock;
 
+
 @end

EasyReader/Application/Models/FeedItem.m

@@ -34,14 +34,11 @@ - (NSString *)feedName
   return feed.name;
 }
 
-- (NSString *)timeAgo
-{
-    return [self.updatedAt timeAgo];
-}
-
 - (NSString *)headline
 {
-    return[NSString stringWithFormat:@"%@ \u00b7 %@",[self feedName],[self timeAgo]];
+    NSString *timeAgo = [self.updatedAt timeAgo];
+    
+    return[NSString stringWithFormat:@"%@ \u00b7 %@", self.feed.name, timeAgo];
 }
 
 + (void) requestFeedItemsFromFeeds:(NSSet  *)feeds

EasyReader/Application/Models/User.h

@@ -12,18 +12,38 @@
 
 @class Feed;
 
+#pragma mark - User -
+
+/**
+ * An EasyReader User generally one per project
+ */
 @interface User : CSBaseObject
 
+
+#pragma mark - Core Data Properties
+
+/// The users feeds
 @property (nonatomic, retain) NSSet *feeds;
+
+
+#pragma mark - Methods
+
+/**
+ * Gets the current user (a singleton shared user)
+ */
++ (User *)current;
+
+
 @end
 
+
+#pragma mark - Core Data Generated Accessors -
+
 @interface User (CoreDataGeneratedAccessors)
 
 - (void)addFeedsObject:(Feed *)value;
 - (void)removeFeedsObject:(Feed *)value;
 - (void)addFeeds:(NSSet *)values;
 - (void)removeFeeds:(NSSet *)values;
 
-+ (User *)current;
-
 @end