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 ... warn about possible problems.

Browse source 
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@12794 72102866-910b-0410-8b05-ffd578937521
This commit is contained in:
CaS 2002-02-26 17:36:33 +00:00
parent 0cb3dfc684
commit 0ab6bf6fef
8 changed files with 151 additions and 25 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
ChangeLog
View file

@ -4,6 +4,9 @@
version of concrete classes to be that of the abstract class which
actually performs encoding/decoding ... should correct archiving.
Problem reported by Gerrit Van Dyk
* Tools/GSIndex.m: tidied a little
* Tools/GSParser.m: mark when things are implemented.
* Tools/GSOutput.m: warn about unimplemented items.
2002-02-26 Pierre-Yves Rivaille <pyrivail@ens-lyon.fr>

29
Documentation/manual/DistributedObjects.texi
View file

@ -809,6 +809,31 @@ this:@*
@code{- changeValue: (@b{inout} int *)number;}
@end example
Passing of arguments by reference is very restricted in Objective-C.
it applies only to pointers to C data types, not to objects, and except
for the special case of a pointer to a nul terminated C string (@b{char*})
the pointer is assumed to refer to a single data item of the specified
type.
@example
/*
* A method passing an unsigned short integer by reference.
*/
@code{- updateCounter: (@b{inout} unsigned shortn *)value;}
/*
* A method passing a structure by reference.
*/
@code{- updateState: (@b{inout} struct stateInfo *)value;}
/*
* As a special case, a char (or equivalent typedef) passed by reference
* is assumed to be a nul terminated string ... there is no way to pass
* a single character by reference:
*/
@code{- updateBuffer: (@b{inout} char *)str;}
@end example
@item The @b{bycopy} and @b{byref} qualifiers can be used in a protocol
when the argument or return type is an object.@*@*
@ -913,13 +938,13 @@ connection itself.
@subsection The Connection Fails
You can register an observer object to receive a notification, in the
form of a @code{connectionDidDie} message, when a registered connection
form of a @code{connectionDidDie:} message, when a registered connection
fails. The argument to this message will be an @code{NSNotification}
object that returns the failed connection when it receives an
@code{object} message.
To receive this 'notification' the observer must implement the
@code{connectionDidDie} method, but can be an instance of any class. The
@code{connectionDidDie:} method, but can be an instance of any class. The
observer can then handle the failure gracefully, by releasing any
references to the failed connection and releasing proxies that used the
connection. Registering an object to receive this notification is

40
Documentation/manual/WorkingWithObjects.texi
View file

@ -121,9 +121,9 @@ The Target-Action paradigm is used a great deal in the GNUstep GUI,
but infrequently in other code, it is most applicable when building
a network of related objects that can interact relatively simply.
The idea is that an object may have a @b{target} ... an instance
The idea is that an object may have a @b{target} @dots{} an instance
variable of type @code{id} which refers to a target object, and
an @b{action} ... an instance variable of type @code{SEL}.
an @b{action} @dots{} an instance variable of type @code{SEL}.
When the object is told to perform its action, it asks the @b{target}
to perform the @b{action}, passing itsself as the argument.
@ -201,7 +201,7 @@ is not known to implement the @code{alert:} message:
@end example
In this case, the compiler will not issue a warning, because it only knows
that @code{anObject} is of type @code{id} ... so it doesn't know what
that @code{anObject} is of type @code{id} @dots{} so it doesn't know what
methods the object implements.
At runtime, the Objective-C runtime library will fail to find a
@ -398,11 +398,11 @@ methods of that class.@*
For instance, the method may return a @b{placeholder} object that
will be replaced by another object depending on the initialisation
method that is sent to it.@*
NB. exception ... it is permitted to return nil on allocation failure.
NB. exception @dots{} it is permitted to return nil on allocation failure.
@item
When an object is initialised, the return value of the initialiser
is the new value of the object (or @b{nil}) ... the initialiser is
is the new value of the object (or @b{nil}) @dots{} the initialiser is
permitted to replace one object with another.
This behavior enables a class to
share objects (and do other tricky things) -
@ -432,7 +432,7 @@ share objects (and do other tricky things) -
In the above example, the @code{initWithLevel:} method is used to
create a crown discovered in a random treasure store. If certain
conditions are met, the system returns a special object ... only
conditions are met, the system returns a special object @dots{} only
one of which may exist and be owned by a character.
In this case, the initialiser for a crown expects a character level
@ -446,11 +446,11 @@ to @code{self} before initialising instance variables and returning
@code{self}.
This is necessary because, unlike in C++ or Java, the Objective-C
language does not enforce initialisation ... so it's up to you as
language does not enforce initialisation @dots{} so it's up to you as
the programmer to ensure that superclasses are permitted to
perform their object initialisation code before the subclass
performs its initialisation (actually, this gives you the flexibility
to change how things are initialised ... but you should obey the
to change how things are initialised @dots{} but you should obey the
conventions unless you are sure you know what you are doing).
An initialiser of any class intended for re-use/subclassing should
@ -463,10 +463,10 @@ subclass receives another object from the superclass initialiser, the
new object needs to have enough memory allocated, and the same
initial instance variable layout, as the original object, or assigning
values into it may overwrite memory that's not part of the initialised
object ... causing a crash or other runtime problems.
object @dots{} causing a crash or other runtime problems.
So, to correct our example, we should only return the special object if
it is a subclass of the original object ...
it is a subclass of the original object @dots{}
@example
if (level > wizardLevel && [crownOfTheEmperor isOwned] == NO
@ -479,7 +479,7 @@ it is a subclass of the original object ...
@end example
The @code{isKindOfClass:} method is used to test that the object we
are intending to return is legitimate ... a subclass of whatever
are intending to return is legitimate @dots{} a subclass of whatever
class the original item (@code{self}) allocated was.
@item
@ -494,7 +494,7 @@ Since the @code{init} method is defined in the root class
(@code{NSObject}), it's quite likely that any class could be initialised
by calling this method. If @code{init} is not the designated initialiser
for your class, you should therefore write an implementation of
@code{init} which @b{does} call the designated initialiser ...
@code{init} which @b{does} call the designated initialiser @dots{}
@example
- (id) init
@ -515,7 +515,7 @@ More sophisticated methods combine allocation, initialisation, and
autoreleasing of objects. These methods return objects which have
been added to the current autorelease pool (see later in this chapter
for details). By convention, these methods have names beginning with
something like the name of the class ...
something like the name of the class @dots{}
@example
+ (Crown*) crown
@ -530,7 +530,7 @@ something like the name of the class ...
@item
You handle deallocation of your objects by writing a @code{dealloc}
method. The last thing that this method needs to do is call the
@code{dealloc} method of the superclass ... since it is normally
@code{dealloc} method of the superclass @dots{} since it is normally
the deallocation method of the root class that actually frees the
memory used by the object.
@ -568,7 +568,7 @@ will do.
@section Protocols
We use tweo types of protocol in Objective-C ... @b{informal} protocols,
We use tweo types of protocol in Objective-C @dots{} @b{informal} protocols,
where we document methods to which objects will respond, and specify
how they should behave, and @b{formal} protocols, where we provide a
list of methods that an object will support in a format where the
@ -589,7 +589,7 @@ can chjeck that an object conforms to a protocol at runtime. Protocols
form an inheritance hierarchy much like that of classes.
A particularly important use of protocols is in defining the methods
that an object in a remote process can respond to ... by setting the
that an object in a remote process can respond to @dots{} by setting the
protocol used by a local proxy object, you can avoid having to send
messages to the remote process to check what methods are available -
you can simply check the local protocol object.
@ -686,10 +686,10 @@ in following simple rules. It's pretty efficient.
@item Garbage collection@*
You build the GNUstep base library with garbage collection, and link
with the Boehm GC library ... then never bother about
with the Boehm GC library @dots{} then never bother about
releasing/deallocating memory. This requires a slightly different
approach to programming ... you need to take care about what happens
when objects are deallocated ... but don't need to worry about
approach to programming @dots{} you need to take care about what happens
when objects are deallocated @dots{} but don't need to worry about
deallocating them.
@end itemize
@ -721,7 +721,7 @@ object gets deallocated.
@end example
@item
A simple retain/release mechanism is not very interesting ... so it's
A simple retain/release mechanism is not very interesting @dots{} so it's
spiced up with autorelease pools. You can use the @code{AUTORELEASE}
macro to call the @code{autorelease} method, which adds an object to
the current autorelease pool. An autorelease pool simply maintains

3
Documentation/manual/manual.texi
View file

@ -59,10 +59,13 @@ into another language, under the above conditions for modified versions.
@contents
@ifnothtml
@iftex
@c Foreword
@include foreword.texi
@end iftex
@end ifnothtml
@ifinfo
@c **Top node and master menu

51
Tools/AGSIndex.m
View file

@ -55,6 +55,10 @@ mergeDictionaries(NSMutableDictionary *dst, NSDictionary *src, BOOL override)
{
[dst setObject: s forKey: k];
}
else if ([s isKindOfClass: [NSArray class]] == YES)
{
[dst setObject: s forKey: k];
}
else if ([s isKindOfClass: [NSDictionary class]] == YES)
{
d = [[NSMutableDictionary alloc] initWithCapacity: [s count]];
@ -88,6 +92,25 @@ mergeDictionaries(NSMutableDictionary *dst, NSDictionary *src, BOOL override)
}
}
}
else if ([d isKindOfClass: [NSArray class]] == YES)
{
if ([s isKindOfClass: [NSArray class]] == NO)
{
NSLog(@"Class missmatch in merge for %@.", stack);
}
else if ([d isEqual: s] == NO)
{
if (override == YES)
{
[dst setObject: s forKey: k];
}
else
{
NSLog(@"Array missmatch in merge for %@. S:%@, D:%@",
stack, s, d);
}
}
}
else if ([d isKindOfClass: [NSDictionary class]] == YES)
{
if ([s isKindOfClass: [NSDictionary class]] == NO)
@ -150,6 +173,7 @@ setDirectory(NSMutableDictionary *dict, NSString *path)
* unitmethods unit-name method-name<br />
* classvars class-name variables-name<br />
* title file-name text<br />
* source file-name array-of-source-files<br />
*/
@implementation AGSIndex
@ -493,6 +517,23 @@ setDirectory(NSMutableDictionary *dict, NSString *path)
[dict setObject: to forKey: from];
}
/**
* Set up an array listing the source files for a particular header.
*/
- (void) setSource: (NSArray*)s forHeader: (NSString*)h
{
NSMutableDictionary *dict;
dict = [refs objectForKey: @"source"];
if (dict == nil)
{
dict = [NSMutableDictionary new];
[refs setObject: dict forKey: @"source"];
RELEASE(dict);
}
[dict setObject: s forKey: h];
}
/**
* Set up a reference for something inside a unit (class, category or protocol)
* We store 'method' and 'ivariable' by ref then unit (class),
@ -543,6 +584,16 @@ setDirectory(NSMutableDictionary *dict, NSString *path)
[r setObject: base forKey: u];
}
/**
* Return a list of source files for the header (or nil)
*/
- (NSArray*) sourcesForHeader: (NSString*)h
{
NSDictionary *dict = [refs objectForKey: @"source"];
return [dict objectForKey: h];
}
/**
* Return a dictionary containing info on all the units containing the
* specified method or instance variable.

4
Tools/AGSOutput.h
View file

@ -45,7 +45,9 @@
to: (NSMutableString*)str;
- (void) outputFunction: (NSDictionary*)d to: (NSMutableString*)str;
- (void) outputInstanceVariable: (NSDictionary*)d to: (NSMutableString*)str;
- (void) outputMethod: (NSDictionary*)d to: (NSMutableString*)str;
- (void) outputMethod: (NSDictionary*)d
to: (NSMutableString*)str
for: (NSString*)unit;
- (void) outputUnit: (NSDictionary*)d to: (NSMutableString*)str;
- (unsigned) reformat: (NSString*)str
withIndent: (unsigned)ind

33
Tools/AGSOutput.m
View file

@ -605,6 +605,10 @@ static BOOL snuggleStart(NSString *t)
NSString *declared = [d objectForKey: @"Declared"];
NSString *standards = nil;
if ([[d objectForKey: @"Implemented"] isEqual: @"YES"] == NO)
{
NSLog(@"Warning ... %@ %@ is not implemented where expected", kind, name);
}
if (standards == nil)
{
standards = [d objectForKey: @"Standards"];
@ -655,6 +659,11 @@ static BOOL snuggleStart(NSString *t)
NSString *standards = nil;
unsigned i = [aa count];
if ([[d objectForKey: @"Implemented"] isEqual: @"YES"] == NO)
{
NSLog(@"Warning ... function %@ is not implemented where expected", name);
}
/**
* Place the names of function arguments in a temporary array 'args'
* so that they will be highlighted if they appear in the function
@ -822,7 +831,9 @@ static BOOL snuggleStart(NSString *t)
* Uses -split: and -reformat:withIndent:to:.
* Also has fun with YES, NO, and nil.
*/
- (void) outputMethod: (NSDictionary*)d to: (NSMutableString*)str
- (void) outputMethod: (NSDictionary*)d
to: (NSMutableString*)str
for: (NSString*)unit
{
NSArray *sels = [d objectForKey: @"Sels"];
NSArray *types = [d objectForKey: @"Types"];
@ -833,6 +844,12 @@ static BOOL snuggleStart(NSString *t)
NSString *override = nil;
NSString *standards = nil;
if (unit != nil && [[d objectForKey: @"Implemented"] isEqual: @"YES"] == NO)
{
NSLog(@"Warning ... method %@ %@ is not implemented where expected",
unit, name);
}
args = [d objectForKey: @"Args"]; // Used when splitting.
comment = [d objectForKey: @"Comment"];
@ -994,6 +1011,7 @@ static BOOL snuggleStart(NSString *t)
NSDictionary *methods = [d objectForKey: @"Methods"];
NSDictionary *ivars = [d objectForKey: @"InstanceVariables"];
NSString *comment = [d objectForKey: @"Comment"];
NSString *unitName = nil;
NSArray *names;
NSArray *protocols;
NSString *standards = nil;
@ -1004,6 +1022,15 @@ static BOOL snuggleStart(NSString *t)
unsigned i;
unsigned j;
if ([[d objectForKey: @"Implemented"] isEqual: @"YES"] == NO)
{
NSLog(@"Warning ... unit %@ is not implemented where expected", name);
}
else
{
unitName = name;
}
r = [comment rangeOfString: @"<standards>"];
if (comment != nil && r.length > 0)
{
@ -1180,7 +1207,9 @@ static BOOL snuggleStart(NSString *t)
{
NSString *mName = [names objectAtIndex: i];
[self outputMethod: [methods objectForKey: mName] to: str];
[self outputMethod: [methods objectForKey: mName]
to: str
for: unitName];
}
if (standards != nil)

13
Tools/AGSParser.m
View file

@ -484,10 +484,12 @@
if (isTypedef == YES)
{
[d setObject: @"Types" forKey: @"Kind"];
[d setObject: @"YES" forKey: @"Implemented"];
}
else if (baseConstant == YES)
{
[d setObject: @"Constants" forKey: @"Kind"];
[d setObject: @"YES" forKey: @"Implemented"];
}
else
{
@ -634,6 +636,13 @@
}
else if (buffer[pos] == '{')
{
/*
* Inline functions may be implemented in the header.
*/
if (isFunction == YES)
{
[d setObject: @"YES" forKey: @"Implemented"];
}
[self skipBlock];
}
else
@ -820,6 +829,8 @@ fail:
[oDecl setObject: tmp forKey: @"Comment"];
}
[oDecl setObject: @"YES" forKey: @"Implemented"];
if ([kind isEqualToString: @"Functions"] == YES)
{
NSArray *a1 = [oDecl objectForKey: @"Args"];
@ -918,6 +929,7 @@ fail:
}
else
{
[dict setObject: @"YES" forKey: @"Implemented"];
/*
* Append any comment we have for this
*/
@ -1603,6 +1615,7 @@ fail:
}
[exist setObject: token forKey: @"Comment"];
}
[exist setObject: @"YES" forKey: @"Implemented"];
}
break;