diff --git a/ChangeLog b/ChangeLog index 6cf8ad996..e5a7d3376 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,4 +1,28 @@ -2002-10-03 Richard Frith-Macdonald +2002-10-05 Richard Frith-Macdonald + + * Tools/AGSOutput.m: Improve warning code, support text output + in chapter/section/subsection. + * Tools/AGSParser.m: move concatenation of comments into a single + method, make it insert a linebreak between concatenated comments, + and make it refrain from appending the same comment onto itsself + (which would happen if the same file was parsed twice, as both a + header and as source). + Treat the 'main()' function specially ... don't document it as a + function but insert its comments at the end of the 'chapter' part + of the output document. These modifications make it easy to + document a directory containing tools, by listing the tool source + files as arguments to autogsdoc. + Tools/gsdoc_0_6_7.dtd: Fix bug preventing use of text in a chapter! + * Source/GSString.m: Implement -UTF8String method for better + performance. + * Source/NSPortNameServer.m: Improve diagnostic message in exception + when reporting failure to register ... try to provide all the info + needed to begin diagnosing any problem. + * Tools/gdomap.c: Make -M flag work with -N. Make -M flag work when + used after -N or -L. Improve diagnostic messages on failure so + people know what it is trying to do. + +2002-10-04 Richard Frith-Macdonald * Source/NSArray.m: Tidied init from file to ensure that everything is released properly on failure, and we don't generate log messages diff --git a/Headers/gnustep/base/NSCalendarDate.h b/Headers/gnustep/base/NSCalendarDate.h index d3bb76095..26b9ae8d3 100644 --- a/Headers/gnustep/base/NSCalendarDate.h +++ b/Headers/gnustep/base/NSCalendarDate.h @@ -135,7 +135,11 @@ @end #ifndef NO_GNUSTEP -NSTimeInterval GSTime(int d, int m, int y, int hh, int mm, int ss, int mil); +void +GSBreakTime(NSTimeInterval when, int *year, int *month, int *day, int *hour, + int *minute, int *second, int *mil); +NSTimeInterval +GSTime(int day, int month, int year, int hour, int minute, int second, int mil); #endif #endif /* __NSCalendarDate_h_GNUSTEP_BASE_INCLUDE*/ diff --git a/Source/GSString.m b/Source/GSString.m index 85a2b0604..c90fb8a7c 100644 --- a/Source/GSString.m +++ b/Source/GSString.m @@ -530,6 +530,78 @@ setup() * peculiar to its memory management (shrinking, growing, and converting). */ +static inline char* +UTF8String_c(ivars self) +{ + unsigned char *r; + + if (self->_count == 0) + { + return ""; + } + if (intEnc == NSISOLatin1StringEncoding || intEnc == NSASCIIStringEncoding) + { + r = (unsigned char*)_fastMallocBuffer(self->_count+1); + + if (self->_count > 0) + { + memcpy(r, self->_contents.c, self->_count); + } + r[self->_count] = '\0'; + } + else + { + unichar *u = 0; + unsigned l = 0; + unsigned s = 0; + + /* + * We must convert from internal format to unicode and then to + * UTF8 string encoding. + */ + if (GSToUnicode(&u, &l, self->_contents.c, self->_count, intEnc, + NSDefaultMallocZone(), 0) == NO) + { + [NSException raise: NSCharacterConversionException + format: @"Can't convert to Unicode string."]; + } + if (GSFromUnicode((unsigned char**)&r, &s, u, l, NSUTF8StringEncoding, + NSDefaultMallocZone(), GSUniTerminate|GSUniTemporary|GSUniStrict) == NO) + { + NSZoneFree(NSDefaultMallocZone(), u); + [NSException raise: NSCharacterConversionException + format: @"Can't convert from Unicode to UTF8."]; + } + NSZoneFree(NSDefaultMallocZone(), u); + } + + return r; +} + +static inline char* +UTF8String_u(ivars self) +{ + unsigned c = self->_count; + + if (c == 0) + { + return ""; + } + else + { + unsigned int l = 0; + unsigned char *r = 0; + + if (GSFromUnicode(&r, &l, self->_contents.u, c, NSUTF8StringEncoding, + NSDefaultMallocZone(), GSUniTerminate|GSUniTemporary|GSUniStrict) == NO) + { + [NSException raise: NSCharacterConversionException + format: @"Can't get UTF8 from Unicode string."]; + } + return r; + } +} + static inline BOOL boolValue_c(ivars self) { @@ -1826,6 +1898,11 @@ transmute(ivars self, NSString *aString) * 8-bit string class, storing immutable data in a single buffer. */ @implementation GSCString +- (const char *) UTF8String +{ + return UTF8String_c((ivars)self); +} + - (BOOL) boolValue { return boolValue_c((ivars)self); @@ -2124,6 +2201,11 @@ transmute(ivars self, NSString *aString) @implementation GSUnicodeString +- (const char *) UTF8String +{ + return UTF8String_u((ivars)self); +} + - (BOOL) boolValue { return boolValue_u((ivars)self); diff --git a/Source/NSCalendarDate.m b/Source/NSCalendarDate.m index cdf46b66a..51a8f0ac8 100644 --- a/Source/NSCalendarDate.m +++ b/Source/NSCalendarDate.m @@ -216,7 +216,7 @@ gregorianDateFromAbsolute(int abs, int *day, int *month, int *year) * External - so NSDate and others can use it. */ NSTimeInterval -GSTime(int day, int month, int year, int h, int m, int s, int mil) +GSTime(int day, int month, int year, int hour, int minute, int second, int mil) { NSTimeInterval a; @@ -225,9 +225,9 @@ GSTime(int day, int month, int year, int h, int m, int s, int mil) // Calculate date as GMT a -= GREGORIAN_REFERENCE; a = (NSTimeInterval)a * 86400; - a += h * 3600; - a += m * 60; - a += s; + a += hour * 3600; + a += minute * 60; + a += second; a += mil/1000.0; return a; } @@ -237,7 +237,7 @@ GSTime(int day, int month, int year, int h, int m, int s, int mil) * elements.
* External - so NSDate and others can use it. */ -static void +void GSBreakTime(NSTimeInterval when, int *year, int *month, int *day, int *hour, int *minute, int *second, int *mil) { diff --git a/Source/NSConnection.m b/Source/NSConnection.m index 14d883a08..625eb3ed6 100644 --- a/Source/NSConnection.m +++ b/Source/NSConnection.m @@ -506,6 +506,7 @@ static BOOL multi_threaded = NO; } /** + * Not used in GNUstep */ + (id) currentConversation { @@ -1164,7 +1165,8 @@ static BOOL multi_threaded = NO; } /** - * Returns YES if the connection is invalid, NO otherwise. + * Returns YES if the connection is valid, NO otherwise. + * A connection is valid until it has been sent an -invalidate message. */ - (BOOL) isValid { @@ -1206,7 +1208,8 @@ static BOOL multi_threaded = NO; /** * Returns YES if the connection permits multiple threads to use it to - * send requests, NO otherwise. + * send requests, NO otherwise.
+ * See the -enableMultipleThreads method. */ - (BOOL) multipleThreadsEnabled { @@ -1486,8 +1489,10 @@ static BOOL multi_threaded = NO; /** * Sets the time interval that the NSConnection will wait for a - * reply to one of its requests before raising an - * NSPortTimeoutException. + * reply for one of its requests before raising an + * NSPortTimeoutException.
+ * NB. In GNUstep you may also get such an exception if the connection + * becomes invalidated while waiting for a reply to a request. */ - (void) setReplyTimeout: (NSTimeInterval)to { diff --git a/Source/NSCountedSet.m b/Source/NSCountedSet.m index c59cb1c37..ae64cee7c 100644 --- a/Source/NSCountedSet.m +++ b/Source/NSCountedSet.m @@ -317,13 +317,13 @@ static Class NSCountedSet_concrete_class; * purge the set even when uniquing is turned off. */ void -GSUPurge(unsigned level) +GSUPurge(unsigned count) { if (uniqueLock != nil) { (*lockImp)(uniqueLock, @selector(lock)); } - [uniqueSet purge: level]; + [uniqueSet purge: count]; if (uniqueLock != nil) { (*unlockImp)(uniqueLock, @selector(unlock)); @@ -339,7 +339,7 @@ GSUPurge(unsigned level) * alter the set even when uniquing is turned off. */ id -GSUSet(id obj, unsigned level) +GSUSet(id anObject, unsigned count) { id found; unsigned i; @@ -348,29 +348,29 @@ GSUSet(id obj, unsigned level) { (*lockImp)(uniqueLock, @selector(lock)); } - found = [uniqueSet member: obj]; + found = [uniqueSet member: anObject]; if (found == nil) { - found = obj; - for (i = 0; i < level; i++) + found = anObject; + for (i = 0; i < count; i++) { - [uniqueSet addObject: obj]; + [uniqueSet addObject: anObject]; } } else { i = [uniqueSet countForObject: found]; - if (i < level) + if (i < count) { - while (i < level) + while (i < count) { [uniqueSet addObject: found]; i++; } } - else if (i > level) + else if (i > count) { - while (i > level) + while (i > count) { [uniqueSet removeObject: found]; i--; @@ -391,7 +391,7 @@ GSUSet(id obj, unsigned level) * If uniquing is turned off, it simply returns its argument. */ id -GSUnique(id obj) +GSUnique(id anObject) { if (uniquing == YES) { @@ -399,13 +399,13 @@ GSUnique(id obj) { (*lockImp)(uniqueLock, @selector(lock)); } - obj = (*uniqueImp)(uniqueSet, @selector(unique:), obj); + anObject = (*uniqueImp)(uniqueSet, @selector(unique:), anObject); if (uniqueLock != nil) { (*unlockImp)(uniqueLock, @selector(unlock)); } } - return obj; + return anObject; } /** diff --git a/Source/NSData.m b/Source/NSData.m index f327d9dd5..4a4ee74f0 100644 --- a/Source/NSData.m +++ b/Source/NSData.m @@ -461,8 +461,8 @@ failure: * and with the specified length. Invokes * -initWithBytesNoCopy:length:freeWhenDone: */ -+ (id) dataWithBytesNoCopy: (void*)bytes - length: (unsigned int)length ++ (id) dataWithBytesNoCopy: (void*)aBuffer + length: (unsigned int)bufferSize freeWhenDone: (BOOL)shouldFree { NSData *d; @@ -475,7 +475,9 @@ failure: { d = [dataStatic allocWithZone: NSDefaultMallocZone()]; } - d = [d initWithBytesNoCopy: bytes length: length freeWhenDone: shouldFree]; + d = [d initWithBytesNoCopy: aBuffer + length: bufferSize + freeWhenDone: shouldFree]; return AUTORELEASE(d); } @@ -592,7 +594,8 @@ failure: * The value fo shouldFree specifies whether the receiver should * attempt to free the memory pointer to by aBuffer when the receiver * is deallocated ... ie. it says whether the receiver owns - * the memory. + * the memory. Supplying the wrong value here will lead to memory + * leaks or crashes. */ - (id) initWithBytesNoCopy: (void*)aBuffer length: (unsigned int)bufferSize diff --git a/Source/NSObjCRuntime.m b/Source/NSObjCRuntime.m index d6971df37..e9f1f8500 100644 --- a/Source/NSObjCRuntime.m +++ b/Source/NSObjCRuntime.m @@ -152,7 +152,7 @@ BOOL GSInstanceVariableInfo(id obj, NSString *iVarName, const char **type, unsigned *size, unsigned *offset) { - const char *name = [iVarName cString]; + const char *name = [iVarName UTF8String]; return GSFindInstanceVariable(obj, name, type, size, offset); } @@ -160,13 +160,13 @@ GSInstanceVariableInfo(id obj, NSString *iVarName, /** ## deprecated ## */ BOOL -GSGetInstanceVariable(id obj, NSString *iVarName, void *data) +GSGetInstanceVariable(id obj, NSString *name, void *data) { - const char *name = [iVarName cString]; + const char *cName = [name UTF8String]; int offset; unsigned int size; - if (GSFindInstanceVariable(obj, name, 0, &size, &offset) == YES) + if (GSFindInstanceVariable(obj, cName, 0, &size, &offset) == YES) { GSGetVariable(obj, offset, size, data); return YES; @@ -177,13 +177,13 @@ GSGetInstanceVariable(id obj, NSString *iVarName, void *data) /** ## deprecated ## */ BOOL -GSSetInstanceVariable(id obj, NSString *iVarName, const void *data) +GSSetInstanceVariable(id obj, NSString *name, const void *data) { - const char *name = [iVarName cString]; + const char *cName = [name UTF8String]; int offset; unsigned int size; - if (GSFindInstanceVariable(obj, name, 0, &size, &offset) == YES) + if (GSFindInstanceVariable(obj, cName, 0, &size, &offset) == YES) { GSSetVariable(obj, offset, size, data); return YES; diff --git a/Source/NSPortNameServer.m b/Source/NSPortNameServer.m index 2202df84c..9ca9aa0d2 100644 --- a/Source/NSPortNameServer.m +++ b/Source/NSPortNameServer.m @@ -584,8 +584,8 @@ typedef enum { return [self portForName: name onHost: nil]; } -- (NSPort*) portForName: (NSString*)name - onHost: (NSString*)host +- (BOOL) _lookupName: (NSString*)name onHost: (NSString*)host + intoAddress: (NSString**)addr andPort: (unsigned*)port { GSPortCom *com = nil; NSRunLoop *loop = [NSRunLoop currentRunLoop]; @@ -593,11 +593,11 @@ typedef enum { struct in_addr *svrs = &singleServer; unsigned numSvrs = 1; unsigned count; - unsigned portNum = 0; unsigned len; NSMutableArray *array; NSDate *limit; + *port = 0; if (name == nil) { [NSException raise: NSInvalidArgumentException @@ -711,7 +711,7 @@ typedef enum { { unsigned i; - portNum = 0; + *port = 0; count = 0; do { @@ -740,13 +740,12 @@ typedef enum { { break; /* No servers left to try! */ } - [loop runMode: mode - beforeDate: limit]; + [loop runMode: mode beforeDate: limit]; /* * Check for completed operations. */ - while (portNum == 0 && i-- > 0) + while (*port == 0 && i-- > 0) { com = [array objectAtIndex: i]; if ([com isActive] == NO) @@ -754,9 +753,8 @@ typedef enum { [com close]; if ([com state] == GSPC_DONE) { - portNum - = GSSwapBigI32ToHost(*(gsu32*)[[com data] bytes]); - if (portNum != 0) + *port = GSSwapBigI32ToHost(*(gsu32*)[[com data] bytes]); + if (*port != 0) { singleServer = [com addr]; } @@ -765,7 +763,7 @@ typedef enum { } } } - while (portNum == 0 && [limit timeIntervalSinceNow] > 0); + while (*port == 0 && [limit timeIntervalSinceNow] > 0); /* * Make sure that any outstanding lookups are cancelled. @@ -788,14 +786,32 @@ typedef enum { NS_ENDHANDLER [serverLock unlock]; - if (portNum) + if (*port) + { + *addr = [NSString stringWithCString: inet_ntoa(singleServer)]; + return YES; + } + else + { + return NO; + } +} + +- (NSPort*) portForName: (NSString*)name + onHost: (NSString*)host +{ + NSString *addr; + unsigned portNum = 0; + + if ([self _lookupName: name + onHost: host + intoAddress: &addr + andPort: &portNum] == YES) { if (portClass == [GSTcpPort class]) { - NSString *addr; NSHost *host; - addr = [NSString stringWithCString: inet_ntoa(singleServer)]; host = [NSHost hostWithAddress: addr]; return (NSPort*)[GSTcpPort portWithNumber: portNum onHost: host @@ -854,7 +870,6 @@ typedef enum { NS_DURING { NSMutableSet *known = NSMapGet(_portMap, port); - GSPortCom *tmp; /* * If there is no set of names for this port - create one. @@ -875,8 +890,7 @@ typedef enum { if ([known count] == 0) { com = [GSPortCom new]; - [com startPortUnregistration: [port portNumber] - withName: nil]; + [com startPortUnregistration: [port portNumber] withName: nil]; while ([limit timeIntervalSinceNow] > 0 && [com isActive] == YES) { [loop runMode: mode @@ -888,18 +902,14 @@ typedef enum { [NSException raise: NSPortTimeoutException format: @"timed out unregistering port"]; } - tmp = com; - com = nil; - RELEASE(tmp); + DESTROY(com); } com = [GSPortCom new]; - [com startPortRegistration: [port portNumber] - withName: name]; + [com startPortRegistration: [port portNumber] withName: name]; while ([limit timeIntervalSinceNow] > 0 && [com isActive] == YES) { - [loop runMode: mode - beforeDate: limit]; + [loop runMode: mode beforeDate: limit]; } [com close]; if ([com state] != GSPC_DONE) @@ -914,19 +924,53 @@ typedef enum { result = GSSwapBigI32ToHost(*(gsu32*)[[com data] bytes]); if (result == 0) { - [NSException raise: NSGenericException - format: @"Unable to register name '%@' for the port -\n%@\n" + unsigned int portNum; + NSString *addr; + BOOL found; + + NS_DURING + { + found = [self _lookupName: name + onHost: @"" + intoAddress: &addr + andPort: &portNum]; + + } + NS_HANDLER + { + found = NO; + } + NS_ENDHANDLER + + if (found == YES) + { + [NSException raise: NSGenericException + format: @"Unable to register name '%@' for the port -\n%@\n" +@"It appears that a process is already registered with this name at port\n" +@"'%d' IP address %@\n" +@"Perhaps this program ran before and was shut down without unregistering,\n" +@"so another process may be running using the same network port. If this is\n" +@"the case, you can use -\n" +@"gdomap -U '%@'\n" +@"to remove the registration so that you can attempt this operation again.", + name, port, portNum, addr, name]; + } + else + { + [NSException raise: NSGenericException + format: @"Unable to register name '%@' for the port -\n%@\n" @"Typically, this might mean that a process is already running with the name\n" @"'%@' ...\n" @"Try the command -\n" -@" gdomap -L '%@'\n" +@" gdomap -M localhost -L '%@'\n" @"to find its network details.\n" @"Alternatively, it may have been shut down without unregistering, and\n" @"another process may be running using the same network port. If this is\n" @"the case, you can use -\n" @"gdomap -U '%@'\n" @"to remove the registration so that you can attempt this operation again.", - name, port, name, name, name]; + name, port, name, name, name]; + } } else { @@ -938,16 +982,14 @@ typedef enum { NSMapInsert(_nameMap, name, port); } } - tmp = com; - com = nil; - RELEASE(tmp); + DESTROY(com); } NS_HANDLER { /* * If we had a problem - close and unlock before continueing. */ - RELEASE(com); + DESTROY(com); [serverLock unlock]; [localException raise]; } diff --git a/Source/NSString.m b/Source/NSString.m index 38d2b2189..55b10fbfd 100644 --- a/Source/NSString.m +++ b/Source/NSString.m @@ -4339,7 +4339,7 @@ handle_printf_atsign (FILE *stream, * Removes the specified prefix from the string. Raises an exception * if the prefix is not present. */ -- (void) deletePrefix: (NSString*)prefix; +- (void) deletePrefix: (NSString*)prefix { NSCAssert2([self hasPrefix: prefix], @"'%@' does not have the prefix '%@'", self, prefix); diff --git a/Tools/AGSHtml.m b/Tools/AGSHtml.m index 336ff8b15..64d92b0c2 100644 --- a/Tools/AGSHtml.m +++ b/Tools/AGSHtml.m @@ -519,6 +519,7 @@ static NSMutableSet *textNodes = nil; ssect = 0; sssect = 0; [self outputNodeList: children to: buf]; + heading = nil; } else if ([name isEqual: @"class"] == YES) { @@ -1086,16 +1087,23 @@ static NSMutableSet *textNodes = nil; } else if ([name isEqual: @"heading"] == YES) { - [buf appendString: indent]; - [buf appendString: @"<"]; - [buf appendString: heading]; - [buf appendString: @">"]; - [buf appendFormat: @"", - chap, sect, ssect, sssect]; - [self outputText: children to: buf]; - [buf appendString: @"\n"]; + if (heading == nil) + { + } + else + { + [buf appendString: indent]; + [buf appendString: @"<"]; + [buf appendString: heading]; + [buf appendString: @">"]; + [buf appendFormat: @"", + chap, sect, ssect, sssect]; + [self outputText: children to: buf]; + [buf appendString: @"\n"]; + heading = nil; + } } else if ([name isEqual: @"index"] == YES) { @@ -1394,6 +1402,7 @@ static NSMutableSet *textNodes = nil; ssect = 0; sssect = 0; [self outputNodeList: children to: buf]; + heading = @"h1"; } else if ([name isEqual: @"site"] == YES) { @@ -1442,12 +1451,14 @@ static NSMutableSet *textNodes = nil; ssect++; sssect = 0; [self outputNodeList: children to: buf]; + heading = @"h2"; } else if ([name isEqual: @"subsubsect"] == YES) { heading = @"h4"; sssect++; [self outputNodeList: children to: buf]; + heading = @"h3"; } else if ([name isEqual: @"type"] == YES) { @@ -1593,14 +1604,28 @@ NSLog(@"Element '%@' not implemented", name); // FIXME RELEASE(arp); } +/** + * Output all the nodes from this one onwards ... try to output + * as text first, if not possible, call the main method to output + * each node. + */ - (void) outputNodeList: (GSXMLNode*)node to: (NSMutableString*)buf { while (node != nil) { GSXMLNode *next = [node nextElement]; + GSXMLNode *tmp; - [self outputNode: node to: buf]; - node = next; + tmp = [self outputText: node to: buf]; + if (tmp == node) + { + [self outputNode: node to: buf]; + node = next; + } + else + { + node = tmp; + } } } diff --git a/Tools/AGSOutput.h b/Tools/AGSOutput.h index 1388fff07..058648a70 100644 --- a/Tools/AGSOutput.h +++ b/Tools/AGSOutput.h @@ -33,6 +33,7 @@ NSCharacterSet *spacenl; // Blanks excluding newline NSArray *args; // Not retained. BOOL verbose; + BOOL warn; } - (NSString*) checkComment: (NSString*)comment @@ -58,7 +59,6 @@ - (unsigned) reformat: (NSString*)str withIndent: (unsigned)ind to: (NSMutableString*)buf; -- (void) setVerbose: (BOOL)flag; - (NSArray*) split: (NSString*)str; @end #endif diff --git a/Tools/AGSOutput.m b/Tools/AGSOutput.m index 101e0ec34..21b7fa6d5 100644 --- a/Tools/AGSOutput.m +++ b/Tools/AGSOutput.m @@ -81,24 +81,24 @@ static BOOL snuggleStart(NSString *t) if ([comment length] == 0) { comment = @"Description forthcoming."; - if (verbose == YES) + if (warn == YES) { NSString *name = [d objectForKey: @"Name"]; NSString *type = [d objectForKey: @"Type"]; if (unit == nil) { - NSLog(@"No comments for %@ %@", type, name); + NSLog(@"Warning - No comments for %@ %@", type, name); } else { if ([d objectForKey: @"ReturnType"] != nil) { - NSLog(@"No comments for [%@ %@]", unit, name); + NSLog(@"Warning - No comments for [%@ %@]", unit, name); } else { - NSLog(@"No comments for instance variable %@ in %@", + NSLog(@"Warning - No comments for instance variable %@ in %@", name, unit); } } @@ -213,6 +213,8 @@ static BOOL snuggleStart(NSString *t) @"_0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"]); identStart = RETAIN([NSCharacterSet characterSetWithCharactersInString: @"_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"]); + verbose = [[NSUserDefaults standardUserDefaults] boolForKey: @"Verbose"]; + warn = [[NSUserDefaults standardUserDefaults] boolForKey: @"Warn"]; return self; } @@ -629,7 +631,7 @@ static BOOL snuggleStart(NSString *t) NSString *declared = [d objectForKey: @"Declared"]; NSString *standards = nil; - if ([[d objectForKey: @"Implemented"] isEqual: @"YES"] == NO) + if (warn == YES && [[d objectForKey: @"Implemented"] isEqual: @"YES"] == NO) { NSLog(@"Warning ... %@ %@ is not implemented where expected", kind, name); } @@ -680,7 +682,7 @@ static BOOL snuggleStart(NSString *t) NSString *standards = nil; unsigned i = [aa count]; - if ([[d objectForKey: @"Implemented"] isEqual: @"YES"] == NO) + if (warn == YES && [[d objectForKey: @"Implemented"] isEqual: @"YES"] == NO) { NSLog(@"Warning ... function %@ is not implemented where expected", name); } @@ -861,7 +863,8 @@ static BOOL snuggleStart(NSString *t) NSString *override = nil; NSString *standards = nil; - if (unit != nil && [[d objectForKey: @"Implemented"] isEqual: @"YES"] == NO) + if (warn == YES && unit != nil + && [[d objectForKey: @"Implemented"] isEqual: @"YES"] == NO) { NSLog(@"Warning ... method %@ %@ is not implemented where expected", unit, name); @@ -1056,7 +1059,7 @@ static BOOL snuggleStart(NSString *t) [m setObject: @"YES" forKey: @"Implemented"]; } } - else + else if (warn == YES) { NSLog(@"Warning ... unit %@ is not implemented where expected", name); } @@ -1393,11 +1396,6 @@ static BOOL snuggleStart(NSString *t) return ind; } -- (void) setVerbose: (BOOL)flag -{ - verbose = flag; -} - - (NSArray*) split: (NSString*)str { NSMutableArray *a = [NSMutableArray arrayWithCapacity: 128]; diff --git a/Tools/AGSParser.h b/Tools/AGSParser.h index 8a8a67262..21549b599 100644 --- a/Tools/AGSParser.h +++ b/Tools/AGSParser.h @@ -61,6 +61,7 @@ BOOL inArgList; BOOL documentAllInstanceVariables; BOOL verbose; + BOOL warn; NSDictionary *wordMap; NSString *declared; /** Where classes were declared. */ NSMutableArray *ifStack; /** Track preprocessor conditionals. */ @@ -93,7 +94,6 @@ - (void) setDocumentAllInstanceVariables: (BOOL)flag; - (void) setGenerateStandards: (BOOL)flag; - (void) setStandards: (NSMutableDictionary*)dict; -- (void) setVerbose: (BOOL)flag; - (void) setWordMap: (NSDictionary*)map; - (void) setupBuffer; - (unsigned) skipArray; diff --git a/Tools/AGSParser.m b/Tools/AGSParser.m index fbf12349c..050e0edb0 100644 --- a/Tools/AGSParser.m +++ b/Tools/AGSParser.m @@ -24,6 +24,83 @@ @implementation AGSParser +/** + * Method to add the comment from the main() function to the end + * of the initial chapter in the output document. We do this to + * support the use of autogsdoc to document tools. + */ +- (void) addMain: (NSString*)c +{ + NSString *chap; + NSMutableString *m; + NSRange r; + + chap = [info objectForKey: @"chapter"]; + if (chap == nil) + { + chap = [NSString stringWithFormat: + @"%@", + [[fileName lastPathComponent] stringByDeletingPathExtension]]; + } + m = [chap mutableCopy]; + r = [m rangeOfString: @""]; + r.length = 0; + [m replaceCharactersInRange: r withString: @"\n"]; + [m replaceCharactersInRange: r withString: c]; + [m replaceCharactersInRange: r withString: + @"
\nThe main() function\n"]; + [info setObject: m forKey: @"chapter"]; + RELEASE(m); +} + +/** + * Append a comment (with leading and trailing space stripped) + * to an information dictionary.
+ * If the dictionary is nil, accumulate in the comment ivar instead.
+ * If the comment is empty, ignore it.
+ * If there is no comment in the dictionary, simply set the new value.
+ * If a comment already exists then the new comment text is appended to + * it with a separating line break inserted if necessary.
+ */ +- (void) appendComment: (NSString*)s to: (NSMutableDictionary*)d +{ + s = [s stringByTrimmingSpaces]; + if ([s length] > 0) + { + NSString *old; + + if (d == nil) + { + old = comment; + } + else + { + old = [d objectForKey: @"Comment"]; + } + if (old != nil) + { + if ([old hasSuffix: @"

"] == NO + && [old hasSuffix: @"
"] == NO + && [old hasSuffix: @"
"] == NO) + { + s = [old stringByAppendingFormat: @"
%@", s]; + } + else + { + s = [old stringByAppendingString: s]; + } + } + if (d == nil) + { + ASSIGN(comment, s); + } + else + { + [d setObject: s forKey: @"Comment"]; + } + } +} + - (void) dealloc { DESTROY(wordMap); @@ -60,6 +137,8 @@ @"_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"]); info = [[NSMutableDictionary alloc] initWithCapacity: 6]; source = [NSMutableArray new]; + verbose = [[NSUserDefaults standardUserDefaults] boolForKey: @"Verbose"]; + warn = [[NSUserDefaults standardUserDefaults] boolForKey: @"Warn"]; return self; } @@ -731,7 +810,7 @@ } if (comment != nil) { - [d setObject: comment forKey: @"Comment"]; + [self appendComment: comment to: d]; } DESTROY(comment); } @@ -750,7 +829,7 @@ /* * Don't bother to warn about nameless enumerations. */ - if ([t isEqual: @"enum ..."] == NO) + if (verbose == YES && [t isEqual: @"enum ..."] == NO) { [self log: @"parse declaration with no name - %@", d]; } @@ -919,19 +998,20 @@ fail: if (oDecl != nil) { - NSString *tmp = [nDecl objectForKey: @"Comment"]; + NSString *oc = [oDecl objectForKey: @"Comment"]; + NSString *nc = [nDecl objectForKey: @"Comment"]; - if (tmp != nil) + /* + * If the old comment from the header parsing is + * the same as the new comment from the source + * parsing, assume we parsed the same file as both + * source and header ... otherwise append the new + * comment. + */ + if ([oc isEqual: nc] == NO) { - NSString *old = [oDecl objectForKey: @"Comment"]; - - if (old != nil) - { - tmp = [old stringByAppendingString: tmp]; - } - [oDecl setObject: tmp forKey: @"Comment"]; + [self appendComment: nc to: oDecl]; } - [oDecl setObject: @"YES" forKey: @"Implemented"]; if ([kind isEqualToString: @"Functions"] == YES) @@ -944,6 +1024,23 @@ fail: [self log: @"Function %@ args missmatch - " @"%@ %@", name, a1, a2]; } + /* + * A main function is not documented as a + * function, but as a special case its + * comments are added to the 'front' + * section of the documentation. + */ + if ([name isEqual: @"main"] == YES) + { + NSString *c; + + c = [oDecl objectForKey: @"Comment"]; + if (c != nil) + { + [self addMain: c]; + } + [dict removeObjectForKey: name]; + } } } } @@ -1036,16 +1133,7 @@ fail: /* * Append any comment we have for this */ - if (tmp != nil) - { - NSString *old = [dict objectForKey: @"Comment"]; - - if (old != nil) - { - tmp = [old stringByAppendingString: tmp]; - } - [dict setObject: tmp forKey: @"Comment"]; - } + [self appendComment: tmp to: dict]; /* * Update base class if necessary. */ @@ -1096,7 +1184,7 @@ fail: */ if (comment != nil) { - [dict setObject: comment forKey: @"Comment"]; + [self appendComment: comment to: dict]; DESTROY(comment); } @@ -1584,18 +1672,7 @@ fail: */ if (comment != nil) { - NSString *old; - - old = [method objectForKey: @"Comment"]; - if (old != nil) - { - [method setObject: [old stringByAppendingString: comment] - forKey: @"Comment"]; - } - else - { - [method setObject: comment forKey: @"Comment"]; - } + [self appendComment: comment to: method]; DESTROY(comment); } @@ -1716,17 +1793,8 @@ fail: } } - token = [method objectForKey: @"Comment"]; - if (token != nil) - { - NSString *old = [exist objectForKey: @"Comment"]; - - if (old != nil) - { - token = [old stringByAppendingString: token]; - } - [exist setObject: token forKey: @"Comment"]; - } + [self appendComment: [method objectForKey: @"Comment"] + to: exist]; [exist setObject: @"YES" forKey: @"Implemented"]; } break; @@ -2099,14 +2167,6 @@ fail: } } -/** - * Control boolean option to do verbose logging of the parsing process. - */ -- (void) setVerbose: (BOOL)flag -{ - verbose = flag; -} - /** * Sets up a dictionary used for mapping identifiers/keywords to other * words. This is used to help cope with cases where C preprocessor @@ -2447,11 +2507,7 @@ fail: NSString *tmp; tmp = [NSString stringWithCharacters: start length: end - start]; - if (comment != nil) - { - tmp = [comment stringByAppendingFormat: @"
\n%@", tmp]; - } - ASSIGN(comment, tmp); + [self appendComment: tmp to: nil]; } if (commentsRead == NO && comment != nil) diff --git a/Tools/autogsdoc.m b/Tools/autogsdoc.m index 3cfb904a8..c0ead6f80 100644 --- a/Tools/autogsdoc.m +++ b/Tools/autogsdoc.m @@ -32,7 +32,7 @@ parse corresponding source files in the same directory as the headers (or the current directory, or the directory specified using the DocumentationDirectory default), and produce gsdoc - files as output. + and html files as output.

Even without any human assistance, this tool will produce skeleton @@ -44,7 +44,18 @@ Any comment beginning with slash and two asterisks rather than the common slash and single asterisk, is taken to be gsdoc markup, to be use as the description of the class or method following it. This - comment text is reformatted and then inserted into the output. + comment text is reformatted and then inserted into the output.
+ Where multiple comments are associatd with the same item, they are + joined together with a line break (<br />) between each if + necessary. +

+

+ The tool can easily be used to document programs as well as libraries, + simply by giving it the name of the source file containing the main() + function of the program - it takes the special comments from that + function and handles them specially, inserting them as a section at + the end of the first chapter of the document (it creates the first + chapter if necessary).

There are some cases where special extra processing is performed, @@ -90,7 +101,9 @@ <chapter> Placed immediately before any generated class documentation ... intended to be used to provide overall description of how the - code being documented works.
+ code being documented works.
Any documentation for the main() + function of a program is inserted as a section at the end of this + chapter. <copy> Copyright of the content of the document ... placed in the head @@ -112,7 +125,7 @@ <title> Title of the document ... placed in the head of the gsdoc output. If this is omitted the tool will generate a (probably poor) - title of its own. + title of its own - so you should include this markup manually. NBThis markup may be used within @@ -178,13 +191,14 @@ Method specifiers including class names (beginning and ending with square brackets) are enclosed in <ref...> ... </ref> markup. -
eg. [ NSObject-init], - will create a reference to the init method of NSObject, while -
[ (NSCopying)-copyWithZone:], creates a +
eg. [NSObject-init], + will create a reference to the init method of NSObject (either the + class proper, or any of its categories), while +
[(NSCopying)-copyWithZone:], creates a reference to a method in the NSCopyIng protocol.
Note that no spaces must appear between the square brackets in these specifiers. -
Protocol namnes are enclosed in round brackets rather than +
Protocol names are enclosed in round brackets rather than the customary angle brackets, because gsdoc is an XML language, and XML treats angle brackets specially. @@ -197,16 +211,16 @@ ConstantsTemplate Specify the name of a template document into which documentation about constants should be inserted from all files in the project.
- This is useful if constanr in the source code are scattered around many + This is useful if constants in the source code are scattered around many files, and you need to group them into one place.
You are responsible for ensuring that the basic template document (into which individual constant documentation is inserted) contains - all the other information you want, but as a conveniencem autogsdoc + all the other information you want, but as a convenience autogsdoc will generate a simple template (which you may then edit) for you if the file does not exist.
Insertion takes place immediately before the back element (or if that does not exist, immediately before the end - of the body lement) in the template. + of the body element) in the template. Declared Specify where headers are to be documented as being found.
@@ -239,7 +253,7 @@ files, and you need to group it into one place.
You are responsible for ensuring that the basic template document (into which individual function documentation is inserted) contains - all the other information you want, but as a conveniencem autogsdoc + all the other information you want, but as a convenience autogsdoc will generate a simple template (which you may then edit) for you if the file does not exist.
Insertion takes place immediately before the back @@ -336,7 +350,7 @@ files, and you need to group it into one place.
You are responsible for ensuring that the basic template document (into which individual typedef documentation is inserted) contains - all the other information you want, but as a conveniencem autogsdoc + all the other information you want, but as a convenience autogsdoc will generate a simple template (which you may then edit) for you if the file does not exist.
Insertion takes place immediately before the back @@ -357,13 +371,21 @@ files, and you need to group it into one place.
You are responsible for ensuring that the basic template document (into which individual variable documentation is inserted) contains - all the other information you want, but as a conveniencem autogsdoc + all the other information you want, but as a convenience autogsdoc will generate a simple template (which you may then edit) for you if the file does not exist.
Insertion takes place immediately before the back element (or if that does not exist, immediately before the end of the body lement) in the template. + Verbose + A boolean used to specify whether you want verbose debug/warning + output to be produced. + + Warn + A boolean used to specify whether you want standard warning + output (eg report of undocumented methods) produced. + WordMap This value is a dictionary used to map identifiers/keywords found in the source files to other words. Generally you will not have @@ -443,6 +465,7 @@ main(int argc, char **argv, char **env) BOOL ignoreDependencies = NO; BOOL showDependencies = NO; BOOL verbose = NO; + BOOL warn = NO; NSArray *files; NSMutableArray *sFiles = nil; // Source NSMutableArray *gFiles = nil; // GSDOC @@ -469,6 +492,7 @@ main(int argc, char **argv, char **env) nil]]; verbose = [defs boolForKey: @"Verbose"]; + warn = [defs boolForKey: @"Warn"]; ignoreDependencies = [defs boolForKey: @"IgnoreDependencies"]; showDependencies = [defs boolForKey: @"ShowDependencies"]; if (ignoreDependencies == YES) @@ -607,9 +631,7 @@ main(int argc, char **argv, char **env) parser = [AGSParser new]; [parser setWordMap: [defs dictionaryForKey: @"WordMap"]]; - [parser setVerbose: verbose]; output = [AGSOutput new]; - [output setVerbose: verbose]; if ([defs boolForKey: @"Standards"] == YES) { [parser setGenerateStandards: YES]; diff --git a/Tools/gdomap.c b/Tools/gdomap.c index 3d9d4ea53..8c115e16f 100644 --- a/Tools/gdomap.c +++ b/Tools/gdomap.c @@ -3854,7 +3854,8 @@ nameServer(const char* name, const char* host, int op, int ptype, struct sockadd rval = tryHost(GDO_SERVERS, 0, 0, ptype, &sin, &num, (uptr*)&b); if (rval != 0 && host == local_hostname) { - sprintf(ebuf, "failed to contact gdomap (%s)\n", strerror(errno)); + sprintf(ebuf, "failed to contact gdomap on %s(%s) - %s", + local_hostname, inet_ntoa(sin.sin_addr), strerror(errno)); gdomap_log(LOG_ERR); return -1; } @@ -3907,7 +3908,8 @@ nameServer(const char* name, const char* host, int op, int ptype, struct sockadd rval = tryHost(op, len, name, ptype, &sin, &port, 0); if (rval != 0 && host == local_hostname) { - sprintf(ebuf, "failed to contact gdomap (%s)", strerror(errno)); + sprintf(ebuf, "failed to contact gdomap on %s(%s) - %s", + local_hostname, inet_ntoa(sin.sin_addr), strerror(errno)); gdomap_log(LOG_ERR); return -1; } @@ -3956,7 +3958,7 @@ lookup(const char *name, const char *host, int ptype) } static void -donames() +donames(const char *host) { struct sockaddr_in sin; struct servent* sp; @@ -3966,7 +3968,6 @@ donames() int rval; uptr b; char *first_dot; - const char *host; #ifdef __MINGW__ char local_hostname[INTERNET_MAX_HOST_NAME_LENGTH]; #else @@ -3986,23 +3987,25 @@ donames() } #endif - /* - * If no host name is given, we use the name of the local host. - * NB. This should always be the case for operations other than lookup. - */ + if (host == 0 || *host == '\0') + { + /* + * If no host name is given, we use the name of the local host. + */ - if (gethostname(local_hostname, sizeof(local_hostname)) < 0) - { - sprintf(ebuf, "gethostname() failed: %s", strerror(errno)); - gdomap_log(LOG_ERR); - return; + if (gethostname(local_hostname, sizeof(local_hostname)) < 0) + { + sprintf(ebuf, "gethostname() failed: %s", strerror(errno)); + gdomap_log(LOG_ERR); + return; + } + first_dot = strchr(local_hostname, '.'); + if (first_dot) + { + *first_dot = '\0'; + } + host = local_hostname; } - first_dot = strchr(local_hostname, '.'); - if (first_dot) - { - *first_dot = '\0'; - } - host = local_hostname; if ((hp = gethostbyname(host)) == 0) { sprintf(ebuf, "gethostbyname() failed: %s", strerror(errno)); @@ -4024,7 +4027,8 @@ donames() rval = tryHost(GDO_NAMES, 0, 0, 0, &sin, &num, (uptr*)&b); if (rval != 0) { - sprintf(ebuf, "failed to contact gdomap (%s)", strerror(errno)); + sprintf(ebuf, "failed to contact gdomap on %s(%s) - %s", + local_hostname, inet_ntoa(sin.sin_addr), strerror(errno)); gdomap_log(LOG_ERR); return; } @@ -4099,11 +4103,13 @@ int main(int argc, char** argv) { extern char *optarg; - char *options = "CHI:L:M:NP:R:T:U:a:bc:dfi:p"; + char *options = "-CHI:L:M:NP:R:T:U:a:bc:dfi:p"; int c; int ptype = GDO_TCP_GDO; int port = 0; const char *machine = 0; + const char *lookupf = 0; + int donamesf = 0; #ifdef HAVE_SYSLOG /* Initially, gdomap_log errors to stderr as well as to syslogd. */ @@ -4154,8 +4160,8 @@ main(int argc, char** argv) printf("-H general help\n"); printf("-I pid file to write pid\n"); printf("-L name perform lookup for name then quit.\n"); - printf("-M name machine name for L (default local)\n"); - printf("-N list all names registered on this host\n"); + printf("-M name machine name for -L and -N\n"); + printf("-N list all names registered on host\n"); printf("-P number port number required for R option.\n"); printf("-R name register name locally then quit.\n"); printf("-T type port type for L, R and U options -\n"); @@ -4220,16 +4226,16 @@ printf( exit(0); case 'L': - lookup(optarg, machine, ptype); - exit(0); + lookupf = optarg; + break; case 'M': machine = optarg; break; case 'N': - donames(); - exit(0); + donamesf = 1; + break; case 'P': port = atoi(optarg); @@ -4415,6 +4421,18 @@ printf( exit(0); } } + if (donamesf || lookupf) + { + if (donamesf) + { + donames(machine); + } + if (lookupf) + { + lookup(lookupf, machine, ptype); + } + exit (0); + } #ifdef __MINGW__ /* On Win32, we don't fork */ if (nofork == 0)