/usr/share/GNUstep/Documentation/Developer/BaseAdditions/Reference/NSObject+GNUstepBase.gsdoc is in gnustep-base-doc 1.25.1-2ubuntu3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 | <?xml version="1.0"?>
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 1.0.4//EN" "http://www.gnustep.org/gsdoc-1_0_4.dtd">
<gsdoc base="NSObject+GNUstepBase" up="BaseAdditions">
<head>
<title>NSObject+GNUstepBase documentation</title>
<author name="Richard Frith-Macdonald">
<email address="rfm@gnu.org">
rfm@gnu.org
</email>
</author>
<copy>2003-2010 Free Software Foundation, Inc.</copy>
</head>
<body>
<front><contents /></front>
<chapter>
<heading>
Software documentation for the NSObject(GNUstepBase)
informal protocol
</heading>
<category name="GNUstepBase" class="NSObject" ovadd="0.0.0">
<declared>GNUstepBase/NSObject+GNUstepBase.h</declared>
<desc>
<em>Description forthcoming.</em>
</desc>
<method type="NSComparisonResult" ovadd="0.0.0">
<sel>compare:</sel>
<arg type="id">anObject</arg>
<desc>
WARNING: The
<ref type="method" id="-compare:">
-compare:
</ref>
method for NSObject is deprecated due to subclasses
declaring the same selector with conflicting
signatures. Comparision of arbitrary objects is
not just meaningless but also dangerous as most
concrete implementations expect comparable objects
as arguments often accessing instance variables
directly. This method will be removed in a future
release.
</desc>
</method>
<method type="BOOL" ovadd="0.0.0">
<sel>isInstance</sel>
<desc>
For backward compatibility only... use
<ref type="function" id="class_isMetaClass">
class_isMetaClass()
</ref>
on the class of the receiver instead.
</desc>
</method>
<method type="BOOL" ovadd="0.0.0">
<sel>makeImmutable</sel>
<desc>
Transmutes the receiver into an immutable
version of the same object. Returns
<code>YES</code> if the receiver has become
immutable, <code>NO</code> otherwise. <br /> The
default implementation returns <code>NO</code>.
<br /> Mutable classes which have an immutable
counterpart they can efficiently change into,
should override to transmute themselves and return
<code>YES</code>. <br /> Immutable classes should
override this to simply return <code>YES</code>
with no further action. <br /> This method is used in
methods which are declared to return immutable
objects (eg. an NSArray), but which create and
build mutable ones internally.
</desc>
</method>
<method type="id" ovadd="0.0.0">
<sel>makeImmutableCopyOnFail:</sel>
<arg type="BOOL">force</arg>
<desc>
DEPRECATED... do not use. Transmutes the
receiver into an immutable version of the same
object and returns the result. <br /> If the
receiver is not a mutable object or cannot be
simply transmuted, then this method either returns
the receiver unchanged or, if the <var>force</var> flag
is set to <code>YES</code>, returns an autoreleased copy
of the receiver. <br /> Mutable classes should override
this default implementation. <br /> This method is
used in methods which are declared to return immutable
objects (eg. an NSArray), but which create and
build mutable ones internally.
</desc>
</method>
<method type="id" ovadd="0.0.0">
<sel>notImplemented:</sel>
<arg type="SEL">aSel</arg>
<desc>
Message sent when an implementation wants to
explicitly exclude a method (but cannot due to
compiler constraint), and wants to make sure it is
not called by mistake. Default implementation raises an
exception at runtime.
</desc>
</method>
<method type="id" ovadd="0.0.0">
<sel>shouldNotImplement:</sel>
<arg type="SEL">aSel</arg>
<desc>
Message sent when an implementation wants to
explicitly exclude a method (but cannot due to
compiler constraint) and forbid that subclasses
implement it. Default implementation raises an
exception at runtime. If a subclass <em>does</em>
implement this method, however, the superclass's
implementation will not be called, so this
is not a perfect mechanism.
</desc>
</method>
<method type="id" ovadd="0.0.0">
<sel>subclassResponsibility:</sel>
<arg type="SEL">aSel</arg>
<desc>
Message sent when an implementation wants to
explicitly require a subclass to implement a
method (but cannot at compile time since there is no
<code>abstract</code> keyword in Objective-C).
Default implementation raises an exception at
runtime to alert developer that he/she forgot to
override a method.
</desc>
</method>
</category>
</chapter>
<chapter>
<heading>
Software documentation for the NSObject(GSAtExit)
informal protocol
</heading>
<category name="GSAtExit" class="NSObject" ovadd="0.0.0">
<declared>GNUstepBase/NSObject+GNUstepBase.h</declared>
<desc>
This is an informal protocol... classes may implement
the method and register themselves to have it called on
process exit.
</desc>
<method type="void" factory="yes" ovadd="0.0.0">
<sel>atExit</sel>
<desc>
This method is called on exit for any class which
implements it and which has called
<ref type="method" id="+registerAtExit">
+registerAtExit
</ref>
to register it to be called. <br /> The order in which
methods for different classes is called is the
reverse of the order in which the classes were
registered, but it's best to assume the method
can not depend on any other class being in a usable
state at the point when the method is called (rather
like +load). <br /> Typical use would be to release
memory occupied by class data structures so that
memory usage analysis software will not think the
memory has been leaked.
</desc>
</method>
</category>
</chapter>
<chapter>
<heading>
Software documentation for the NSObject(GSCleanup)
informal protocol
</heading>
<category name="GSCleanup" class="NSObject" ovadd="0.0.0">
<declared>GNUstepBase/NSObject+GNUstepBase.h</declared>
<desc>
Category for methods handling leaked memory cleanup
on exit of process (for use when debugging memory leaks).
<br /> You enable this by calling the
<ref type="method" id="+setShouldCleanUp:">
+setShouldCleanUp:
</ref>
method (done implicitly by gnustep-base if the
GNUSTEP_SHOULD_CLEAN_UP environment
variable is set to <code>YES</code>). <br /> Your
class then has two options for performing cleanup when
the process ends:
<p>
1. Use the <ref type="method" id="+leak:">+leak:</ref>
method to register objects which are simply to be
retained until the process ends, and then either
ignored or released depending on the cleanup
setting in force. This mechanism is simple and
should be sufficient for many classes.
</p>
<p>
2. Implement a
<ref type="method" id="+atExit">
+atExit
</ref>
method to be run when the process ends and, within
your
<ref type="method" id="+initialize">
+initialize
</ref>
implementation, call
<ref type="method" id="+shouldCleanUp">
+shouldCleanUp
</ref>
to determine whether cleanup should be done, and if it
returns <code>YES</code> then call
<ref type="method" id="+registerAtExit">
+registerAtExit
</ref>
to have your
<ref type="method" id="+atExit">
+atExit
</ref>
method called when the process terminates.
</p>
<p>
The order in which 'leaked' objects are released and
<ref type="method" id="+atExit">
+atExit
</ref>
methods are called on process exist is the reverse
of the order in which they werse set up suing this API.
</p>
</desc>
<method type="id" factory="yes" ovadd="0.0.0">
<sel>leak:</sel>
<arg type="id">anObject</arg>
<desc>
This method simply retains its argument so that it
will never be deallocated during normal operation, but
keeps track of it so that it is released during
process exit if cleanup is enabled. <br /> Returns
its argument.
</desc>
</method>
<method type="id" factory="yes" ovadd="0.0.0">
<sel>leakAt:</sel>
<arg type="id*">anAddress</arg>
<desc>
This method retains the object at *anAddress so that
it will never be deallocated during normal operation,
but keeps track of the address so that the object is
released and the address is zeroed during process
exit if cleanup is enabled. <br /> Returns the object
at *anAddress.
</desc>
</method>
<method type="BOOL" factory="yes" ovadd="0.0.0">
<sel>registerAtExit</sel>
<desc>
Sets the receiver to have its
<ref type="method" id="+atExit">
+atExit
</ref>
method called at the point when the process
terminates. <br /> Returns <code>YES</code> on
success and <code>NO</code> on failure (if the
class does not implement the method or if it is
already registered to call it). <br /> Implemented
as a call to
<ref type="method" id="+registerAtExit:">
+registerAtExit:
</ref>
with the selector for the
<ref type="method" id="+atExit">
+atExit
</ref>
method as its argument.
</desc>
</method>
<method type="BOOL" factory="yes" ovadd="0.0.0">
<sel>registerAtExit:</sel>
<arg type="SEL">aSelector</arg>
<desc>
Sets the receiver to have the specified method called
at the point when the process terminates. <br /> Returns
<code>YES</code> on success and <code>NO</code> on
failure (if the class does not implement the method
ir if it is already registered to call it).
</desc>
</method>
<method type="void" factory="yes" ovadd="0.0.0">
<sel>setShouldCleanUp:</sel>
<arg type="BOOL">aFlag</arg>
<desc>
Specifies the default cleanup behavior on process
exit... the value returned by the NSObject
implementation of the
<ref type="method" id="+shouldClanUp">
+shouldClanUp
</ref>
method. <br /> Calling this method with a
<code>YES</code> argument implicitly calls the
<ref type="method" id="+enableAtExit">
+enableAtExit
</ref>
method as well. <br /> The GNUstep Base library
calls this method with the value obtained from the
GNUSTEP_SHOULD_CLEAN_UP environment
variable when NSObject is initialised.
</desc>
</method>
<method type="BOOL" factory="yes" ovadd="0.0.0">
<sel>shouldCleanUp</sel>
<desc>
Returns a flag indicating whether the receiver
should clean up its data structures etc at process
exit. <br /> The NSObject implementation returns the
value set by the
<ref type="method" id="+setShouldCleanUp:">
+setShouldCleanUp:
</ref>
method but subclasses may override this.
</desc>
</method>
</category>
</chapter>
<chapter>
<heading>
Software documentation for the
NSObject(MemoryFootprint) informal
protocol
</heading>
<category name="MemoryFootprint" class="NSObject" ovadd="0.0.0">
<declared>GNUstepBase/NSObject+GNUstepBase.h</declared>
<desc>
This is an informal protocol... classes may implement
the method to report how much memory is used by the
instance and any objects it acts as a container for.
</desc>
<method type="NSUInteger" ovadd="0.0.0">
<sel>sizeInBytesExcluding:</sel>
<arg type="NSHashTable*">exclude</arg>
<desc>
<em>Description forthcoming.</em>
</desc>
</method>
</category>
</chapter>
</body>
</gsdoc>
|