Better documentation.

NSArray+Coby.m

@@ -3,13 +3,13 @@
 @implementation NSArray (Coby)
 
 // # Access
-
-// Returns the tail of the array, returns an empty array if the subarray
-// is out of range.
 //
-//      NSArray *anArray = [NSArray arrayWithObjects:@"One", "@Two", "@Three"];
-//      [anArray from:0]; => [@"One", @"Two", @"Three"]
-//      [anArray from:10]; => []
+// Returns the tail of the array, returns an empty array if the
+// subarray is out of range.
+//
+//      NSArray *r = [NSArray arrayWithObjects:@"1", "@2", "@3", nil];
+//      [r from:0]; => [@"1", @"2", @"3"]
+//      [r from:10]; => []
 //
 - (NSArray *)from:(NSUInteger)position {
   if( position >= [self count]) return [NSArray array];
@@ -21,7 +21,8 @@ - (NSArray *)to:(NSUInteger)position {
   return [self first:(position + 1)];
 }
 
-// Returns the first `n` elements, if it's empty return an empty `NSArray`
+// Returns the first `n` elements, if it's empty return an empty
+// `NSArray`
 - (NSArray *)first:(NSUInteger)numberOfElements {
   if([self count] == 0) return [NSArray array];
 
@@ -32,10 +33,10 @@ - (NSArray *)first:(NSUInteger)numberOfElements {
 // These pretty much describe themselves. They just add some
 // handy accessors to your arrays without needing to check indices
 //
-//      NSArray *anArray = [NSArray arrayWithObjects:@"One", "@Two", "@Three"];
-//      [anArray first] => @"One"
-//      [anArray third] => @"Three"
-//      [anArray fourth] => nil
+//      NSArray *r = [NSArray arrayWithObjects:@"1", "@2", "@3", nil];
+//      [r first] => @"3"
+//      [r third] => @"3"
+//      [r fourth] => nil
 //
 - (id)first {
   return [self CB_safeObjectAtIndex:0];
@@ -68,18 +69,35 @@ - (id)CB_safeObjectAtIndex:(NSUInteger)index {
   return [self objectAtIndex:index];
 }
 
+// # Manipulation
+//
+//
+//      NSArray *r = [NSArray arrayWithObjects:@"1", @"2", nil];
+//      [r join] => @"12"
+-(NSString *)join {
+  return [self componentsJoinedByString:@""];
+}
+
+// Only added because join reads much easier than
+// `componentsJoinedByString`, and I keep forgetting the
+// latter.
 -(NSString *)join:(NSString *)seperator {
   return [self componentsJoinedByString:seperator];
 }
 
-// Inspired by https://github.com/mikeash/MACollectionUtilities/blob/master/MACollectionUtilities.m
-// But ditched the prefixed naming scheme, since I don't really see the point in
-// doing so.
+// Inspired by [MACollectionUtilities](https://github.com/mikeash/MACollectionUtilities/blob/master/MACollectionUtilities.m)
+// But ditched the prefixed naming scheme, since I don't
+// really see the point in doing so.
+//
+// For example `select` could clash with the `select` for
+// `NSObject` (in UIResponders) however, if those two clash
+// you have a bigger problem than calling it on an array imho.
 //
-// For example `select` could clash with the `select` for `NSObject` (in UIResponders)
-// however, if those two clash you have a bigger problem than calling it on an array.
 // So no prefixing, in favor of simpler method names.
 
+
+// Invokes the block once for each element of self, replacing the
+// element with the value returned by block.
 - (NSArray *)map: (id (^)(id obj))block {
   NSMutableArray *array = [NSMutableArray arrayWithCapacity: [self count]];
   for(id obj in self)
@@ -92,6 +110,9 @@ - (void)each: (void (^)(id obj))block {
     block(obj);
 }
 
+// Invokes the block passing in successive elements from self,
+// returning an array containing those elements for which the block
+// returns a true value.
 - (NSArray *)select: (BOOL (^)(id obj))block {
   NSMutableArray *array = [NSMutableArray array];
   for(id obj in self)
@@ -100,6 +121,8 @@ - (NSArray *)select: (BOOL (^)(id obj))block {
   return array;
 }
 
+// Passes each element of the collection to the given block. The
+// method returns true if the block never returns false or nil.
 - (BOOL)all: (BOOL (^)(id obj))block {
     BOOL match = YES;
     for(id obj in self)
@@ -108,6 +131,7 @@ - (BOOL)all: (BOOL (^)(id obj))block {
     return match;
 }
 
+// Returns a new array by removing duplicate values in self.
 - (NSArray*)uniq {
     return [[NSSet setWithArray:self] allObjects];
 }