From ffe285e7f315562963d3296eac7cc9cac7c873c1 Mon Sep 17 00:00:00 2001 From: "jon.m.reid" Date: Wed, 14 Oct 2009 05:10:35 +0000 Subject: [PATCH] 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 --- Source/Core/Core/HCIs.mm | 2 +- Source/Core/Core/HCIsNot.mm | 2 +- Source/Core/HCBaseDescription.h | 10 +++++++++- Source/Core/HCBaseDescription.mm | 1 + Source/Core/HCStringDescription.h | 6 ++++++ Source/Core/HCStringDescription.mm | 4 ++-- Source/Core/Internal/HCCollectMatchers.h | 3 +++ Source/Core/Internal/HCIntegerTypes.h | 6 +++++- Source/Core/Internal/HCWrapShortcut.h | 7 ++++++- Source/Core/Internal/HCWrapShortcut.mm | 2 +- Source/Core/Internal/NSObject_HCSelfDescribingValue.h | 8 ++++++++ Source/Library/Collection/HCIsCollectionContaining.mm | 2 +- .../Library/Collection/HCIsCollectionOnlyContaining.mm | 4 ++-- Source/Library/Collection/HCIsDictionaryContaining.mm | 4 ++-- .../Library/Collection/HCIsDictionaryContainingKey.mm | 2 +- .../Collection/HCIsDictionaryContainingValue.mm | 2 +- Source/Library/Object/HCHasDescription.mm | 2 +- Source/Library/Text/HCRequireNonNilString.h | 3 +++ 18 files changed, 54 insertions(+), 16 deletions(-) diff --git a/Source/Core/Core/HCIs.mm b/Source/Core/Core/HCIs.mm index 8e534f3..4444574 100644 --- a/Source/Core/Core/HCIs.mm +++ b/Source/Core/Core/HCIs.mm @@ -56,7 +56,7 @@ - (void) describeTo:(id)description id 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 index 2b785b9..a55571d 100644 --- a/Source/Core/Core/HCIsNot.mm +++ b/Source/Core/Core/HCIsNot.mm @@ -56,7 +56,7 @@ - (void) describeTo:(id)description id 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 index 14f6328..1ff462e 100644 --- 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 index 3076af7..ff540fc 100644 --- a/Source/Core/HCBaseDescription.mm +++ b/Source/Core/HCBaseDescription.mm @@ -34,6 +34,7 @@ @implementation HCBaseDescription return self; } + - (id) appendValue:(id)value { if (value == nil) diff --git a/Source/Core/HCStringDescription.h b/Source/Core/HCStringDescription.h index eb8ad76..75f371f 100644 --- a/Source/Core/HCStringDescription.h +++ b/Source/Core/HCStringDescription.h @@ -27,8 +27,14 @@ */ + (NSString*) stringFrom:(id)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 index 265ac79..3b3a583 100644 --- 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 index 45a6ddd..e93f887 100644 --- 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 matcher, va_list args); #ifdef __cplusplus diff --git a/Source/Core/Internal/HCIntegerTypes.h b/Source/Core/Internal/HCIntegerTypes.h index 4557dc6..e5c21cb 100644 --- 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 index 38e0871..d4539e4 100644 --- a/Source/Core/Internal/HCWrapShortcut.h +++ b/Source/Core/Internal/HCWrapShortcut.h @@ -12,7 +12,12 @@ extern "C" { #endif -id 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 HC_wrapInMatcher(id item); #ifdef __cplusplus } diff --git a/Source/Core/Internal/HCWrapShortcut.mm b/Source/Core/Internal/HCWrapShortcut.mm index 1095dae..9b6b596 100644 --- a/Source/Core/Internal/HCWrapShortcut.mm +++ b/Source/Core/Internal/HCWrapShortcut.mm @@ -15,7 +15,7 @@ extern "C" { -id HC_wrapShortcut(id item) +id 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 index 32b230e..66c081b 100644 --- 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)description; @end diff --git a/Source/Library/Collection/HCIsCollectionContaining.mm b/Source/Library/Collection/HCIsCollectionContaining.mm index 9d27324..6d6a8b5 100644 --- a/Source/Library/Collection/HCIsCollectionContaining.mm +++ b/Source/Library/Collection/HCIsCollectionContaining.mm @@ -75,7 +75,7 @@ - (void) describeTo:(id)description id 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 index 7808d70..c35307d 100644 --- a/Source/Library/Collection/HCIsCollectionOnlyContaining.mm +++ b/Source/Library/Collection/HCIsCollectionOnlyContaining.mm @@ -80,14 +80,14 @@ - (void) describeTo:(id)description id 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 index 594738f..5048f34 100644 --- a/Source/Library/Collection/HCIsDictionaryContaining.mm +++ b/Source/Library/Collection/HCIsDictionaryContaining.mm @@ -80,8 +80,8 @@ - (void) describeTo:(id)description id 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 index 9a944b1..44a35c5 100644 --- a/Source/Library/Collection/HCIsDictionaryContainingKey.mm +++ b/Source/Library/Collection/HCIsDictionaryContainingKey.mm @@ -71,7 +71,7 @@ - (void) describeTo:(id)description id 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 index 056b491..ec12fff 100644 --- a/Source/Library/Collection/HCIsDictionaryContainingValue.mm +++ b/Source/Library/Collection/HCIsDictionaryContainingValue.mm @@ -71,7 +71,7 @@ - (void) describeTo:(id)description id 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 index 0679e45..a98b90a 100644 --- a/Source/Library/Object/HCHasDescription.mm +++ b/Source/Library/Object/HCHasDescription.mm @@ -58,7 +58,7 @@ - (void) describeTo:(id)description id 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 index 6a87326..a1da0e8 100644 --- 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) {