Doxygen comment changes and renaming of internal functions

git-svn-id: http://hamcrest.googlecode.com/svn/trunk/hamcrest-objectivec@469 2aa0e9f1-8e24-0410-adc4-1b6a3a6e65e2
aspitz · Oct 14, 2009 · ffe285e · ffe285e
1 parent 3691886
commit ffe285e
Show file tree

Hide file tree

Showing 18 changed files with 54 additions and 16 deletions.
diff --git a/Source/Core/Core/HCIs.mm b/Source/Core/Core/HCIs.mm
@@ -56,7 +56,7 @@ - (void) describeTo:(id<HCDescription>)description
 
 id<HCMatcher> HC_is(id item)
 {
-    return [HCIs is:HC_wrapShortcut(item)];
+    return [HCIs is:HC_wrapInMatcher(item)];
 }
 
 }   // extern "C"
diff --git a/Source/Core/Core/HCIsNot.mm b/Source/Core/Core/HCIsNot.mm
@@ -56,7 +56,7 @@ - (void) describeTo:(id<HCDescription>)description
 
 id<HCMatcher> HC_isNot(id item)
 {
-    return [HCIsNot isNot:HC_wrapShortcut(item)];
+    return [HCIsNot isNot:HC_wrapInMatcher(item)];
 }
 
 }   // extern "C"
diff --git a/Source/Core/HCBaseDescription.h b/Source/Core/HCBaseDescription.h
@@ -17,6 +17,14 @@
 @end
 
 
+/**
+    Methods that must be provided by subclasses of HCBaseDescription.
+*/
 @interface HCBaseDescription (SubclassMustImplement)
-- (void) append:(NSString*)string;
+
+/**
+    Append the string @a str to the description.
+*/
+- (void) append:(NSString*)str;
+
 @end
diff --git a/Source/Core/HCBaseDescription.mm b/Source/Core/HCBaseDescription.mm
@@ -34,6 +34,7 @@ @implementation HCBaseDescription
     return self;
 }
 
+
 - (id<HCDescription>) appendValue:(id)value
 {
     if (value == nil)

diff --git a/Source/Core/HCStringDescription.h b/Source/Core/HCStringDescription.h
@@ -27,8 +27,14 @@
 */
 + (NSString*) stringFrom:(id<HCSelfDescribing>)selfDescribing;
 
+/**
+    Returns an empty description.
+*/
 + (HCStringDescription*) stringDescription;
 
+/**
+    Returns an initialized HCStringDescription object that is empty.
+*/
 - (id) init;
 
 @end
diff --git a/Source/Core/HCStringDescription.mm b/Source/Core/HCStringDescription.mm
@@ -51,9 +51,9 @@ - (NSString*) description
 }
 
 
-- (void) append:(NSString*)string
+- (void) append:(NSString*)str
 {
-    [accumulator appendString:string];
+    [accumulator appendString:str];
 }
 
 @end
diff --git a/Source/Core/Internal/HCCollectMatchers.h b/Source/Core/Internal/HCCollectMatchers.h
@@ -18,6 +18,9 @@
 extern "C" {
 #endif
 
+/**
+    Returns an array of matchers from a variable-length comma-separated list terminated by @c nil.
+*/
 NSMutableArray* HC_collectMatchers(id<HCMatcher> matcher, va_list args);
 
 #ifdef __cplusplus

diff --git a/Source/Core/Internal/HCIntegerTypes.h b/Source/Core/Internal/HCIntegerTypes.h
@@ -5,7 +5,11 @@
 //  Created by: Jon Reid
 //
 
-// Define Leopard types for Tiger
+/**
+    \file
+    Define Leopard integer types for Tiger
+*/
+
 #if !defined(OBJC_API_VERSION) || OBJC_API_VERSION < 2
 
 typedef long NSInteger;

diff --git a/Source/Core/Internal/HCWrapShortcut.h b/Source/Core/Internal/HCWrapShortcut.h
@@ -12,7 +12,12 @@
 extern "C" {
 #endif
 
-id<HCMatcher> HC_wrapShortcut(id item);
+/**
+    Returns @a item wrapped (if necessary) in an HCIsEqual matcher.
+    
+    @a item is returned as-is if it is already an HCMatcher.
+*/
+id<HCMatcher> HC_wrapInMatcher(id item);
 
 #ifdef __cplusplus
 }

diff --git a/Source/Core/Internal/HCWrapShortcut.mm b/Source/Core/Internal/HCWrapShortcut.mm
@@ -15,7 +15,7 @@
 
 extern "C" {
 
-id<HCMatcher> HC_wrapShortcut(id item)
+id<HCMatcher> HC_wrapInMatcher(id item)
 {
     if ([item conformsToProtocol:@protocol(HCMatcher)])
         return item;

diff --git a/Source/Core/Internal/NSObject_HCSelfDescribingValue.h b/Source/Core/Internal/NSObject_HCSelfDescribingValue.h
@@ -11,8 +11,16 @@
 @protocol HCDescription;
 
 
+/**
+    This category allows any object to satisfy the HCSelfDescribing protocol.
+*/
 @interface NSObject (HCSelfDescribingValue)
 
+/**
+    Generates a description of the object.
+
+    @param description The description to be appended to.
+*/
 - (void) describeTo:(id<HCDescription>)description;
 
 @end
diff --git a/Source/Library/Collection/HCIsCollectionContaining.mm b/Source/Library/Collection/HCIsCollectionContaining.mm
@@ -75,7 +75,7 @@ - (void) describeTo:(id<HCDescription>)description
 
 id<HCMatcher> HC_hasItem(id item)
 {
-    return [HCIsCollectionContaining isCollectionContaining:HC_wrapShortcut(item)];
+    return [HCIsCollectionContaining isCollectionContaining:HC_wrapInMatcher(item)];
 }
 
 

diff --git a/Source/Library/Collection/HCIsCollectionOnlyContaining.mm b/Source/Library/Collection/HCIsCollectionOnlyContaining.mm
@@ -80,14 +80,14 @@ - (void) describeTo:(id<HCDescription>)description
 
 id<HCMatcher> HC_onlyContains(id item, ...)
 {
-    NSMutableArray* matcherList = [NSMutableArray arrayWithObject:HC_wrapShortcut(item)];
+    NSMutableArray* matcherList = [NSMutableArray arrayWithObject:HC_wrapInMatcher(item)];
 
     va_list args;
     va_start(args, item);
     item = va_arg(args, id);
     while (item != nil)
     {
-        [matcherList addObject:HC_wrapShortcut(item)];
+        [matcherList addObject:HC_wrapInMatcher(item)];
         item = va_arg(args, id);
     }
     va_end(args);

diff --git a/Source/Library/Collection/HCIsDictionaryContaining.mm b/Source/Library/Collection/HCIsDictionaryContaining.mm
@@ -80,8 +80,8 @@ - (void) describeTo:(id<HCDescription>)description
 
 id<HCMatcher> HC_hasEntry(id key, id value)
 {
-    return [HCIsDictionaryContaining isDictionaryContainingKey:HC_wrapShortcut(key)
-                                                         value:HC_wrapShortcut(value)];
+    return [HCIsDictionaryContaining isDictionaryContainingKey:HC_wrapInMatcher(key)
+                                                         value:HC_wrapInMatcher(value)];
 }
 
 }   // extern "C"
diff --git a/Source/Library/Collection/HCIsDictionaryContainingKey.mm b/Source/Library/Collection/HCIsDictionaryContainingKey.mm
@@ -71,7 +71,7 @@ - (void) describeTo:(id<HCDescription>)description
 
 id<HCMatcher> HC_hasKey(id item)
 {
-    return [HCIsDictionaryContainingKey isDictionaryContainingKey:HC_wrapShortcut(item)];
+    return [HCIsDictionaryContainingKey isDictionaryContainingKey:HC_wrapInMatcher(item)];
 }
 
 }   // extern "C"
diff --git a/Source/Library/Collection/HCIsDictionaryContainingValue.mm b/Source/Library/Collection/HCIsDictionaryContainingValue.mm
@@ -71,7 +71,7 @@ - (void) describeTo:(id<HCDescription>)description
 
 id<HCMatcher> HC_hasValue(id item)
 {
-    return [HCIsDictionaryContainingValue isDictionaryContainingValue:HC_wrapShortcut(item)];
+    return [HCIsDictionaryContainingValue isDictionaryContainingValue:HC_wrapInMatcher(item)];
 }
 
 }   // extern "C"
diff --git a/Source/Library/Object/HCHasDescription.mm b/Source/Library/Object/HCHasDescription.mm
@@ -58,7 +58,7 @@ - (void) describeTo:(id<HCDescription>)description
 
 id<HCMatcher> HC_hasDescription(id item)
 {
-    return [HCHasDescription hasDescription:HC_wrapShortcut(item)];
+    return [HCHasDescription hasDescription:HC_wrapInMatcher(item)];
 }
 
 }   // extern "C"
diff --git a/Source/Library/Text/HCRequireNonNilString.h b/Source/Library/Text/HCRequireNonNilString.h
@@ -11,6 +11,9 @@
 
 namespace hamcrest {
 
+/**
+    Throws an NSException if @a string is nil.
+*/
 inline
 void requireNonNilString(NSString* string)
 {