From c07f4619197608bad18f6801c6052853e528275b Mon Sep 17 00:00:00 2001 From: CaS Date: Wed, 2 Jan 2002 06:50:30 +0000 Subject: [PATCH] Documentation improvements git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@11932 72102866-910b-0410-8b05-ffd578937521 --- ChangeLog | 8 ++ Headers/gnustep/base/NSUserDefaults.h | 4 + Source/GNUmakefile | 5 +- Tools/AGSHtml.m | 136 ++++++++++++++++---------- Tools/AGSParser.h | 3 +- Tools/AGSParser.m | 136 +++++++++++++++++++------- Tools/autogsdoc.m | 11 +++ 7 files changed, 210 insertions(+), 93 deletions(-) diff --git a/ChangeLog b/ChangeLog index 7afa0d582..3b6c175e3 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,11 @@ +2002-01-01 Richard Frith-Macdonald + + * Source/GNUmakefile: Use new -Standards flag for autogsdoc + * Tools/AGSparser.[hm]: New support for standards and some tidyups + * Tools/AGSHtml.[hm]: Improved output and simplified a little. + * Tools/autogsdoc.m: New Standards flag to turn on support for + generation of standards complience notes in documentation. + Tue Jan 1 11:18:35 2002 Nicola Pero * Source/NSFileManager.m (custom_strdup): New inline function diff --git a/Headers/gnustep/base/NSUserDefaults.h b/Headers/gnustep/base/NSUserDefaults.h index 683922c11..117c6184c 100644 --- a/Headers/gnustep/base/NSUserDefaults.h +++ b/Headers/gnustep/base/NSUserDefaults.h @@ -136,8 +136,12 @@ GS_EXPORT NSString* const NSLocale; */ + (void) resetStandardUserDefaults; #endif +#ifndef STRICT_OPENSTEP +#ifndef STRICT_MACOS_X + (NSArray*) userLanguages; + (void) setUserLanguages: (NSArray*)languages; +#endif +#endif /* Initializing the User Defaults */ - (id) init; diff --git a/Source/GNUmakefile b/Source/GNUmakefile index 71b199d14..8a644d84b 100644 --- a/Source/GNUmakefile +++ b/Source/GNUmakefile @@ -429,7 +429,10 @@ libgnustep-base_HEADER_FILES = $(FOUNDATION_HEADERS) DOCUMENT_NAME = Base Base_AGSDOC_FILES = $(FOUNDATION_HEADERS) -Base_AGSDOC_FLAGS = -HeaderDirectory ../Headers/Foundation -Declared Foundation +Base_AGSDOC_FLAGS = \ + -HeaderDirectory ../Headers/Foundation \ + -Declared Foundation \ + -Standards YES -include Makefile.preamble diff --git a/Tools/AGSHtml.m b/Tools/AGSHtml.m index a1c2cf584..d43d2639e 100644 --- a/Tools/AGSHtml.m +++ b/Tools/AGSHtml.m @@ -488,6 +488,27 @@ static NSMutableSet *textNodes = nil; [buf appendString: @"
\n"]; } } + else if ([name isEqual: @"declared"] == YES) + { + [buf appendString: indent]; + [buf appendString: @"
\n"]; + [self incIndent]; + [buf appendString: indent]; + [buf appendString: @"
\n"]; + [self incIndent]; + [buf appendString: indent]; + [buf appendString: @"
Declared in:
\n"]; + [buf appendString: indent]; + [buf appendString: @"
"]; + [self outputText: [node children] to: buf]; + [buf appendString: @"
\n"]; + [self decIndent]; + [buf appendString: indent]; + [buf appendString: @"
\n"]; + [self decIndent]; + [buf appendString: indent]; + [buf appendString: @"
\n"]; + } else if ([name isEqual: @"desc"] == YES) { [buf appendString: indent]; @@ -985,19 +1006,7 @@ static NSMutableSet *textNodes = nil; children = [node next]; if ([[children name] isEqual: @"standards"]) { - tmp = [children children]; - if (tmp != nil) - { - [buf appendString: indent]; - [buf appendString: @"Standards:"]; - while (tmp != nil) - { - [buf appendString: @" "]; - [buf appendString: [tmp name]]; - tmp = [tmp next]; - } - [buf appendString: @"
\n"]; - } + [self outputNode: children to: buf]; } if ((str = [prop objectForKey: @"init"]) != nil @@ -1100,6 +1109,32 @@ static NSMutableSet *textNodes = nil; [self outputText: children to: buf]; [buf appendString: @""]; } + else if ([name isEqual: @"standards"]) + { + GSXMLNode *tmp = [node children]; + BOOL first = YES; + + if (tmp != nil) + { + [buf appendString: indent]; + [buf appendString: @"Standards:"]; + while (tmp != nil) + { + if (first == YES) + { + first = NO; + [buf appendString: @" "]; + } + else + { + [buf appendString: @", "]; + } + [buf appendString: [tmp name]]; + tmp = [tmp next]; + } + [buf appendString: @"
\n"]; + } + } else if ([name isEqual: @"strong"] == YES) { [buf appendString: @""]; @@ -1135,10 +1170,7 @@ static NSMutableSet *textNodes = nil; if (node != nil && [[node name] isEqual: @"declared"] == YES) { - [buf appendString: indent]; - [buf appendString: @"Declared: "]; - [self outputText: [node children] to: buf]; - [buf appendString: @"
\n"]; + [self outputNode: node to: buf]; node = [node next]; } if (node != nil && [[node name] isEqual: @"desc"] == YES) @@ -1450,29 +1482,13 @@ NSLog(@"Element '%@' not implemented", name); // FIXME - (void) outputUnit: (GSXMLNode*)node to: (NSMutableString*)buf { + GSXMLNode *t; NSMutableArray *a; node = [node children]; if (node != nil && [[node name] isEqual: @"declared"] == YES) { - [buf appendString: indent]; - [buf appendString: @"
\n"]; - [self incIndent]; - [buf appendString: indent]; - [buf appendString: @"
\n"]; - [self incIndent]; - [buf appendString: indent]; - [buf appendString: @"
Declared in:
\n"]; - [buf appendString: indent]; - [buf appendString: @"
"]; - [self outputText: [node children] to: buf]; - [buf appendString: @"
\n"]; - [self decIndent]; - [buf appendString: indent]; - [buf appendString: @"
\n"]; - [self decIndent]; - [buf appendString: indent]; - [buf appendString: @"
\n"]; + [self outputNode: node to: buf]; node = [node next]; } @@ -1510,6 +1526,38 @@ NSLog(@"Element '%@' not implemented", name); // FIXME node = [node next]; } + t = node; + while (t != nil && [[t name] isEqual: @"standards"] == NO) + { + t = [t next]; + } + if (t != nil && [t children] != nil) + { + t = [t children]; + [buf appendString: indent]; + [buf appendString: @"
\n"]; + [self incIndent]; + [buf appendString: indent]; + [buf appendString: @"Standards:\n"]; + [buf appendString: indent]; + [buf appendString: @"
    \n"]; + [self incIndent]; + while (t != nil) + { + [buf appendString: indent]; + [buf appendString: @"
  • "]; + [buf appendString: [t name]]; + [buf appendString: @"
    • \n"]; + t = [t next]; + } + [self decIndent]; + [buf appendString: indent]; + [buf appendString: @"
\n"]; + [self decIndent]; + [buf appendString: indent]; + [buf appendString: @"
\n"]; + } + a = [localRefs methodsInUnit: unit]; if ([a count] > 0) { @@ -1545,24 +1593,6 @@ NSLog(@"Element '%@' not implemented", name); // FIXME [self outputNode: node to: buf]; node = [node next]; } - if (node != nil && [[node name] isEqual: @"standards"] == YES) - { - GSXMLNode *tmp = [node children]; - - if (tmp != nil) - { - [buf appendString: indent]; - [buf appendString: @"Standards:"]; - while (tmp != nil) - { - [buf appendString: @" "]; - [buf appendString: [tmp name]]; - tmp = [tmp next]; - } - [buf appendString: @"
\n"]; - } - node = [node next]; - } } /** diff --git a/Tools/AGSParser.h b/Tools/AGSParser.h index 7b80bee1a..fa55d0fea 100644 --- a/Tools/AGSParser.h +++ b/Tools/AGSParser.h @@ -81,6 +81,8 @@ - (NSMutableArray*) parseProtocolList; - (void) reset; - (void) setDeclared: (NSString*)name; +- (void) setGenerateStandards: (BOOL)flag; +- (void) setStandards: (NSMutableDictionary*)dict; - (void) setupBuffer; - (unsigned) skipBlock; - (unsigned) skipComment; @@ -92,6 +94,5 @@ - (unsigned) skipStatementLine; - (unsigned) skipUnit; - (unsigned) skipWhiteSpace; -- (void) setStandards: (NSMutableDictionary*)dict; @end #endif diff --git a/Tools/AGSParser.m b/Tools/AGSParser.m index 38bdd4762..32a29f638 100644 --- a/Tools/AGSParser.m +++ b/Tools/AGSParser.m @@ -57,7 +57,6 @@ identStart = RETAIN([NSCharacterSet characterSetWithCharactersInString: @"_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"]); info = [[NSMutableDictionary alloc] initWithCapacity: 6]; - ifStack = [[NSMutableArray alloc] initWithCapacity: 4]; return self; } @@ -1206,6 +1205,96 @@ fail: ASSIGN(declared, name); } +/** + * Turn on or off parsing of preprocessor conditional compilation info + * indicating the standards complied with. When this is turned on, we + * assume that all standards are complied with by default.
+ * You should only turn this on while parsing the GNUstep source code. + */ +- (void) setGenerateStandards: (BOOL)flag +{ + if (flag == NO) + { + DESTROY(ifStack); + } + else if (ifStack == nil) + { + ifStack = [[NSMutableArray alloc] initWithCapacity: 4]; + [ifStack addObject: @"OpenStep"]; + [ifStack addObject: @"MacOS-X"]; + [ifStack addObject: @"GNUstep"]; + } +} + +/** + * Store the current standards information derived from preprocessor + * conditionals in the supplied dictionary ... this will be used by + * the AGSOutput class to put standards markup in the gsdoc output. + */ +- (void) setStandards: (NSMutableDictionary*)dict +{ + unsigned c = [ifStack count]; + BOOL hadG = NO; + BOOL hadM = NO; + BOOL hadO = NO; + + if (c > 0) + { + NSMutableString *s = nil; + BOOL found = NO; + + s = [NSMutableString stringWithCString: ""]; + while (c-- > 0) + { + NSString *name = [ifStack objectAtIndex: c]; + + /* + * We don't produce output for empty strings or + * the 'NotGNUstep' string. + */ + if ([name isEqualToString: @""] == YES + || [name isEqualToString: @"NotGNUstep"] == YES) + { + continue; + } + if ([name isEqualToString: @"GNUstep"] == YES + || [name isEqualToString: @"NotGNUstep"] == YES) + { + if (hadG == YES) + { + continue; + } + hadG = YES; + } + if ([name isEqualToString: @"OpenStep"] == YES + || [name isEqualToString: @"NotOpenStep"] == YES) + { + if (hadO == YES) + { + continue; + } + hadO = YES; + } + if ([name isEqualToString: @"MacOS-X"] == YES + || [name isEqualToString: @"NotMacOS-X"] == YES) + { + if (hadM == YES) + { + continue; + } + hadM = YES; + } + found = YES; + [s appendFormat: @"<%@ />", name]; + } + if (found == YES) + { + [s appendString: @""]; + [dict setObject: s forKey: @"Standards"]; + } + } +} + /** * Read in the file to be parsed and store it in a temporary unicode * buffer. Perform basic transformations on the buffer to simplify @@ -1821,6 +1910,14 @@ fail: */ - (unsigned) skipPreprocessor { + /* + * If we are not doing preprocessor handling ... just skip to end of line. + */ + if (ifStack == nil) + { + return [self skipRemainderOfLine]; + } + while (pos < length && [spaces characterIsMember: buffer[pos]] == YES) { pos++; @@ -2107,42 +2204,5 @@ fail: return pos; } -/** - * Store the current standards information derived from preprocessor - * conditionals in the supplied dictionary ... this will be used by - * the AGSOutput class to put standards markup in the gsdoc output. - */ -- (void) setStandards: (NSMutableDictionary*)dict -{ - unsigned c = [ifStack count]; - - if (c > 0) - { - NSMutableString *s = nil; - BOOL found = NO; - - s = [NSMutableString stringWithCString: ""]; - while (c-- > 0) - { - NSString *name = [ifStack objectAtIndex: c]; - - /* - * We don't produce output for empty strings or - * the 'NotGNUstep' string. - */ - if ([name isEqualToString: @""] == NO - && [name isEqualToString: @"NotGNUstep"] == NO) - { - found = YES; - [s appendFormat: @"<%@ />", name]; - } - } - if (found == YES) - { - [s appendString: @""]; - [dict setObject: s forKey: @"Standards"]; - } - } -} @end diff --git a/Tools/autogsdoc.m b/Tools/autogsdoc.m index c0b44e7cf..8a2a5ed00 100644 --- a/Tools/autogsdoc.m +++ b/Tools/autogsdoc.m @@ -252,6 +252,14 @@ log which files are being regenerated because of their dependencies on other files. + Standards + A boolean value used to specify whether the program should insert + information about standards complience into ythe documentation. + This should only be used when documenting the GNUstep libraries + and tools themselves as it assumes that the code being documented + is part of GNUstep and possibly complies with the OpenStep standard + or implements MacOS-X compatible methods. + SourceDirectory May be used to specify the directory to be searched for source (anything other than .h files ... which are controlled @@ -342,6 +350,7 @@ main(int argc, char **argv, char **env) BOOL showDependencies = NO; BOOL autoIndex = NO; BOOL modifiedRefs = NO; + BOOL standards = NO; NSDate *rDate = nil; NSMutableArray *files = nil; CREATE_AUTORELEASE_POOL(outer); @@ -359,6 +368,7 @@ main(int argc, char **argv, char **env) nil]]; autoIndex = [defs boolForKey: @"AutoIndex"]; + standards = [defs boolForKey: @"Standards"]; ignoreDependencies = [defs boolForKey: @"IgnoreDependencies"]; showDependencies = [defs boolForKey: @"ShowDependencies"]; if (ignoreDependencies == YES) @@ -464,6 +474,7 @@ main(int argc, char **argv, char **env) prjRefs = [AGSIndex new]; indexer = [AGSIndex new]; parser = [AGSParser new]; + [parser setGenerateStandards: standards]; output = [AGSOutput new]; /*