gnustep/libs-base
0
0
Fork 0
mirror of https://github.com/gnustep/libs-base.git synced 2025-04-22 16:33:29 +00:00
Code Issues Projects Releases Packages Wiki Activity

Improve documentation generation

Browse source 
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@12399 72102866-910b-0410-8b05-ffd578937521
This commit is contained in:
Richard Frith-Macdonald 2002-02-03 17:21:20 +00:00
parent 0d428a62d8
commit fc4d23e09f
10 changed files with 187 additions and 48 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
ChangeLog
View file

@ -1,3 +1,19 @@
2002-02-03 Richard Frith-Macdonald <rfm@gnu.org>
* Source/GNUmakefile: use -WordMap flag with autogsdoc to cope with
C-preprocessor constants that would otherwise confuse parsing.
* Source/NSDictionary.m: Tidy to match interface.
* Source/NSDistantObject.m: Tidy to match interface.
* Source/NSPortCoder.m: Tidy to match interface.
* Source/NSScanner.m: Tidy to match interface. Remove some illegal
semicolons after method names.
* Source/NSTimer.m: Tidy to match interface.
* Tools/AGSParser.h: Handle word mappings.
* Tools/AGSParser.m: Handle word mappings and deal with function
attributes.
* Tools/autogsdoc.m: Handle word mappings and make default logging
less verbose.
2002-02-02 Richard Frith-Macdonald <rfm@gnu.org>
* Source/NSObject.m: Fix some maptable problems when using non-local

8
Source/GNUmakefile
View file

@ -381,7 +381,13 @@ Base_AGSDOC_FLAGS = \
-HeaderDirectory ../Headers/Foundation \
-Declared Foundation \
-Standards YES \
-Up Base
-WordMap '{\
FOUNDATION_EXPORT=extern;FOUNDATION_STATIC_INLINE="";\
GS_GEOM_SCOPE=extern;GS_GEOM_ATTR="";\
GS_EXPORT=extern;GS_DECLARE="";\
GS_RANGE_SCOPE=extern;GS_RANGE_ATTR="";\
GS_ZONE_SCOPE=extern;GS_ZONE_ATTR="";\
}' -Up Base
-include Makefile.preamble

27
Source/NSDictionary.m
View file

@ -354,12 +354,18 @@ static SEL appSel;
return [self initWithObjects: NULL forKeys: NULL count: 0];
}
- (id) initWithDictionary: (NSDictionary*)other
- (id) initWithDictionary: (NSDictionary*)otherDictionary
{
return [self initWithDictionary: other copyItems: NO];
return [self initWithDictionary: otherDictionary copyItems: NO];
}
- (id) initWithDictionary: (NSDictionary*)other copyItems: (BOOL)shouldCopy
/**
* Initialise dictionary with the keys and values of otherDictionary.
* If the shouldCopy flag is YES then the values are copied into the
* newly initialised dictionary, otherwise they are simply retained.
*/
- (id) initWithDictionary: (NSDictionary*)other
copyItems: (BOOL)shouldCopy
{
unsigned c = [other count];
@ -1062,19 +1068,24 @@ static NSString *indentStrings[] = {
}
}
- (void) addEntriesFromDictionary: (NSDictionary*)other
/**
* Merges information from otherDictionary into the receiver.
* If a key exists in both dictionaries, the value from otherDictionary
* replaces that which was originally in the reciever.
*/
- (void) addEntriesFromDictionary: (NSDictionary*)otherDictionary
{
if (other != nil && other != self)
if (otherDictionary != nil && otherDictionary != self)
{
id k;
NSEnumerator *e = [other keyEnumerator];
NSEnumerator *e = [otherDictionary keyEnumerator];
IMP nxtObj = [e methodForSelector: nxtSel];
IMP getObj = [other methodForSelector: objSel];
IMP getObj = [otherDictionary methodForSelector: objSel];
IMP setObj = [self methodForSelector: setSel];
while ((k = (*nxtObj)(e, nxtSel)) != nil)
{
(*setObj)(self, setSel, (*getObj)(other, objSel, k), k);
(*setObj)(self, setSel, (*getObj)(otherDictionary, objSel, k), k);
}
}
}

2
Source/NSDistantObject.m
View file

@ -68,7 +68,7 @@ enum
PROXY_LOCAL_FOR_RECEIVER = 0,
PROXY_LOCAL_FOR_SENDER,
PROXY_REMOTE_FOR_BOTH
};
} proxyLocation;

6
Source/NSPortCoder.m
View file

@ -329,7 +329,7 @@ static IMP _xRefImp; /* Serialize a crossref. */
+ (NSPortCoder*) portCoderWithReceivePort: (NSPort*)recv
sendPort: (NSPort*)send
components: (NSArray*)comp;
components: (NSArray*)comp
{
id coder;
@ -1266,11 +1266,11 @@ static IMP _xRefImp; /* Serialize a crossref. */
* array, and simply record the array index, so the corresponding decode
* method can tell which component to use.
*/
- (void) encodePortObject: (NSPort*)anObject
- (void) encodePortObject: (NSPort*)aPort
{
unsigned pos = [_comp count];
[_comp addObject: anObject];
[_comp addObject: aPort];
[self encodeValueOfObjCType: @encode(unsigned) at: &pos];
}

26
Source/NSScanner.m
View file

@ -708,7 +708,7 @@ typedef struct {
* containing the scanned characters is returned by reference in value.
*/
- (BOOL) scanCharactersFromSet: (NSCharacterSet *)aSet
intoString: (NSString **)value;
intoString: (NSString **)value
{
unsigned int saveScanLocation = _scanLocation;
@ -766,8 +766,8 @@ typedef struct {
* If value is non-NULL, and any characters were scanned, a string
* containing the scanned characters is returned by reference in value.
*/
- (BOOL) scanUpToCharactersFromSet: (NSCharacterSet *)set
intoString: (NSString **)value;
- (BOOL) scanUpToCharactersFromSet: (NSCharacterSet *)aSet
intoString: (NSString **)value
{
unsigned int saveScanLocation = _scanLocation;
unsigned int start;
@ -776,18 +776,18 @@ typedef struct {
if (!skipToNextField())
return NO;
if (set == _charactersToBeSkipped)
if (aSet == _charactersToBeSkipped)
memImp = _skipImp;
else
memImp = (BOOL (*)(NSCharacterSet*, SEL, unichar))
[set methodForSelector: memSel];
[aSet methodForSelector: memSel];
start = _scanLocation;
if (_isUnicode)
{
while (_scanLocation < myLength())
{
if ((*memImp)(set, memSel, myUnicode(_scanLocation)) == YES)
if ((*memImp)(aSet, memSel, myUnicode(_scanLocation)) == YES)
break;
_scanLocation++;
}
@ -796,7 +796,7 @@ typedef struct {
{
while (_scanLocation < myLength())
{
if ((*memImp)(set, memSel, myChar(_scanLocation)) == YES)
if ((*memImp)(aSet, memSel, myChar(_scanLocation)) == YES)
break;
_scanLocation++;
}
@ -826,17 +826,17 @@ typedef struct {
* If value is non-NULL, and the characters at the scan location match aString,
* a string containing the matching string is returned by reference in value.
*/
- (BOOL) scanString: (NSString *)aString intoString: (NSString **)value;
- (BOOL) scanString: (NSString *)string intoString: (NSString **)value
{
NSRange range;
unsigned int saveScanLocation = _scanLocation;
skipToNextField();
range.location = _scanLocation;
range.length = [aString length];
range.length = [string length];
if (range.location + range.length > myLength())
return NO;
range = [_string rangeOfString: aString
range = [_string rangeOfString: string
options: _caseSensitive ? 0 : NSCaseInsensitiveSearch
range: range];
if (range.length == 0)
@ -857,8 +857,8 @@ typedef struct {
* If value is non-NULL, and any characters were scanned, a string
* containing the scanned characters is returned by reference in value.
*/
- (BOOL) scanUpToString: (NSString *)aString
intoString: (NSString **)value;
- (BOOL) scanUpToString: (NSString *)string
intoString: (NSString **)value
{
NSRange range;
NSRange found;
@ -867,7 +867,7 @@ typedef struct {
skipToNextField();
range.location = _scanLocation;
range.length = myLength() - _scanLocation;
found = [_string rangeOfString: aString
found = [_string rangeOfString: string
options: _caseSensitive ? 0 : NSCaseInsensitiveSearch
range: range];
if (found.length)

22
Source/NSTimer.m
View file

@ -46,25 +46,25 @@ static Class NSDate_class;
}
}
/*
/**
* <init />
* Initialise a newly allocated NSTimer object.
*/
- (id) initWithTimeInterval: (NSTimeInterval)seconds
targetOrInvocation: (id)t
selector: (SEL)sel
userInfo: info
- (id) initWithTimeInterval: (NSTimeInterval)ti
targetOrInvocation: (id)object
selector: (SEL)selector
userInfo: (id)info
repeats: (BOOL)f
{
if (seconds <= 0)
if (ti <= 0)
{
seconds = 0.0001;
ti = 0.0001;
}
_interval = seconds;
_interval = ti;
_date = [[NSDate_class allocWithZone: [self zone]]
initWithTimeIntervalSinceNow: seconds];
_target = t;
_selector = sel;
initWithTimeIntervalSinceNow: ti];
_target = object;
_selector = selector;
_info = info;
_repeats = f;
return self;

4
Tools/AGSParser.h
View file

@ -59,6 +59,8 @@
BOOL inInstanceVariables;
BOOL inArgList;
BOOL documentAllInstanceVariables;
BOOL verbose;
NSDictionary *wordMap;
NSString *declared; /** Where classes were declared. */
NSMutableArray *ifStack; /** Track preprocessor conditionals. */
@ -89,6 +91,8 @@
- (void) setDocumentAllInstanceVariables: (BOOL)flag;
- (void) setGenerateStandards: (BOOL)flag;
- (void) setStandards: (NSMutableDictionary*)dict;
- (void) setVerbose: (BOOL)flag;
- (void) setWordMap: (NSDictionary*)map;
- (void) setupBuffer;
- (unsigned) skipArray;
- (unsigned) skipBlock;

104
Tools/AGSParser.m
View file

@ -26,6 +26,7 @@
- (void) dealloc
{
DESTROY(wordMap);
DESTROY(ifStack);
DESTROY(declared);
DESTROY(info);
@ -272,6 +273,7 @@
NSString *s;
BOOL isTypedef = NO;
BOOL isPointer = NO;
BOOL isFunction = NO;
BOOL baseConstant = NO;
BOOL needScalarType = NO;
@ -574,6 +576,7 @@
if (isPointer == NO || [d objectForKey: @"Suffix"] == nil)
{
[d setObject: @"function" forKey: @"Kind"];
isFunction = YES;
}
}
@ -595,6 +598,27 @@
}
else
{
if (isFunction == YES)
{
NSString *ident = [self parseIdentifier];
if ([ident isEqual: @"__attribute__"] == YES)
{
if ([self skipSpaces] < length && buffer[pos] == '(')
{
[self skipBlock]; // Skip the attributes
}
else
{
[self log: @"strange format function attributes"];
}
}
else if (ident != nil)
{
[self log: @"ignoring '%@' in function declaration", ident];
}
}
if (buffer[pos] == ';')
{
[self skipStatement];
@ -631,7 +655,10 @@
{
[d setObject: comment forKey: @"Comment"];
}
[self log: @"parse '%@'", d];
if (verbose == YES)
{
[self log: @"parse '%@'", d];
}
DESTROY(comment);
}
@ -1021,10 +1048,19 @@ fail:
return nil;
}
/**
* Attempt to parse an identifier/keyword (with optional whitespace in
* front of it). Perform mappings using the wordMap dictionary. If a
* mapping produces an empty string, we treat it as if we had read
* whitespace and try again.
* If we read end of data, or anything which is invalid inside an
* identifier, we return nil.
*/
- (NSString*) parseIdentifier
{
unsigned start;
try:
[self skipWhiteSpace];
if (pos >= length || [identStart characterIsMember: buffer[pos]] == NO)
{
@ -1035,8 +1071,21 @@ fail:
{
if ([identifier characterIsMember: buffer[pos]] == NO)
{
return [NSString stringWithCharacters: &buffer[start]
length: pos - start];
NSString *tmp;
NSString *val;
tmp = [NSString stringWithCharacters: &buffer[start]
length: pos - start];
val = [wordMap objectForKey: tmp];
if (val == nil)
{
return tmp; // No mapping found.
}
else if ([val length] > 0)
{
return val; // Got mapped identifier.
}
goto try; // Mapping removed the identifier.
}
pos++;
}
@ -1849,6 +1898,24 @@ 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
* definitions are confusing the parsing process.
*/
- (void) setWordMap: (NSDictionary*)map
{
ASSIGNCOPY(wordMap, map);
}
/**
* Read in the file to be parsed and store it in a temporary unicode
* buffer. Perform basic transformations on the buffer to simplify
@ -2001,12 +2068,22 @@ fail:
}
/**
* Skip until we encounter an '}' marking the end of a block.
* Skip a bracketed block.
* Expect the current character position to be pointing to the
* '{' at the start of a block.
* bracket at the start of a block.
*/
- (unsigned) skipBlock
{
unichar term = '}';
if (buffer[pos] == '(')
{
term = ')';
}
else if (buffer[pos] == '[')
{
term = ']';
}
pos++;
while ([self skipWhiteSpace] < length)
{
@ -2029,8 +2106,21 @@ fail:
[self skipBlock];
break;
case '}':
return pos;
case '(':
pos--;
[self skipBlock];
break;
case '[':
pos--;
[self skipBlock];
break;
default:
if (c == term)
{
return pos;
}
}
}
return pos;

20
Tools/autogsdoc.m
View file

@ -246,7 +246,7 @@
items in this project.
</item>
<item><strong>Projects</strong>
This value may be supplies as a dictionary containing the paths to
This value may be supplied as a dictionary containing the paths to
the igsdoc index/reference files used by external projects, along
with values to be used to map the filenames found in the indexes.<br />
For example, if a project index (igsdoc) file says that the class
@ -289,6 +289,13 @@
If this is missing or set to an empty string, then no 'up' link
will be provided in the documents.
</item>
<item><strong>WordMap</strong>
This value is a dictionary used to map identifiers/keywords found
in the source files to other words. Generally you will not have
to use this, but it is sometimes helpful to avoid the parser being
confused by the use of C preprocessor macros. You can effectively
redefine the macro to something less confusing.
</item>
</list>
<section>
<heading>Inter-document linkage</heading>
@ -430,9 +437,12 @@ main(int argc, char **argv, char **env)
gFiles = [NSMutableArray array];
hFiles = [NSMutableArray array];
count = [files count];
NSLog(@"Proc ... %@", proc);
NSLog(@"Name ... %@", [proc processName]);
NSLog(@"Files ... %@", files);
if (verbose == YES)
{
NSLog(@"Proc ... %@", proc);
NSLog(@"Name ... %@", [proc processName]);
NSLog(@"Files ... %@", files);
}
for (i = 1; i < count; i++)
{
NSString *arg = [files objectAtIndex: i];
@ -484,6 +494,8 @@ NSLog(@"Files ... %@", files);
pool = [NSAutoreleasePool new];
parser = [AGSParser new];
[parser setWordMap: [defs dictionaryForKey: @"WordMap"]];
[parser setVerbose: verbose];
output = [AGSOutput new];
if ([defs boolForKey: @"Standards"] == YES)
{