ObjFW  Check-in [f27905c199]

Overview
Comment:Several documentation improvements
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: f27905c199cdf5c9484bcf0f9c034986ae61e51077f1bfeb1bacfd3805ce5a8c
User & Date: js on 2020-04-19 15:24:24
Other Links: manifest | tags
Context
2020-04-21
19:51
Fix AmigaOS and devkitPro build check-in: d57a77b9cd user: js tags: trunk
2020-04-19
15:24
Several documentation improvements check-in: f27905c199 user: js tags: trunk
14:52
Reduce usage of unions check-in: e0459c419c user: js tags: trunk
Changes

Modified src/OFApplication.h from [d0ae1ccee1] to [ae508719d0].

16
17
18
19
20
21
22


23
24
25
26
27
28
29
30
























31
32
33
34
35
36
37
 */

#include <signal.h>

#import "OFObject.h"

OF_ASSUME_NONNULL_BEGIN



@class OFArray OF_GENERIC(ObjectType);
@class OFDictionary OF_GENERIC(KeyType, ObjectType);
@class OFMutableArray OF_GENERIC(ObjectType);
@class OFMutableDictionary OF_GENERIC(KeyType, ObjectType);
@class OFSandbox;
@class OFString;

























#define OF_APPLICATION_DELEGATE(class_)					\
	int								\
	main(int argc, char *argv[])					\
	{								\
		return of_application_main(&argc, &argv,		\
		    (class_ *)[[class_ alloc] init]);			\
	}







>
>








>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







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
 */

#include <signal.h>

#import "OFObject.h"

OF_ASSUME_NONNULL_BEGIN

/*! @file */

@class OFArray OF_GENERIC(ObjectType);
@class OFDictionary OF_GENERIC(KeyType, ObjectType);
@class OFMutableArray OF_GENERIC(ObjectType);
@class OFMutableDictionary OF_GENERIC(KeyType, ObjectType);
@class OFSandbox;
@class OFString;

/*!
 * @brief Specify the class to be used as the application delegate.
 *
 * An instance of this class will be created and act as the application
 * delegate.
 *
 * For example, it can be used like this:
 *
 * @code
 * // In MyAppDelegate.h:
 * @interface MyAppDelegate: OFObject <OFApplicationDelegate>
 * @end
 *
 * // In MyAppDelegate.m:
 * OF_APPLICATION_DELEGATE(MyAppDelegate)
 *
 * @implementation MyAppDelegate
 * - (void)applicationDidFinishLaunching
 * {
 *         [OFApplication terminate];
 * }
 * @end
 * @endcode
 */
#define OF_APPLICATION_DELEGATE(class_)					\
	int								\
	main(int argc, char *argv[])					\
	{								\
		return of_application_main(&argc, &argv,		\
		    (class_ *)[[class_ alloc] init]);			\
	}

Modified src/OFObject.h from [4e03fe9cf9] to [0775955f65].

743
744
745
746
747
748
749
750
751
752









753
754










755
756
757
758
759
760
761
762
763
 * @return The class of the object
 */
+ (id)copy;

/*!
 * @brief Initializes an already allocated object.
 *
 * Derived classes may override this, but need to do
 * @code
 *   self = [super init]









 * @endcode
 * before they do any initialization themselves. @ref init may never return










 * `nil`, instead an exception (for example @ref
 * OFInitializationFailedException) should be thrown.
 *
 * @return An initialized object
 */
- (instancetype)init;

/*!
 * @brief Returns the method signature for the specified selector.







|

|
>
>
>
>
>
>
>
>
>

<
>
>
>
>
>
>
>
>
>
>
|
|







743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762

763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
 * @return The class of the object
 */
+ (id)copy;

/*!
 * @brief Initializes an already allocated object.
 *
 * Derived classes may override this, but need to use the following pattern:
 * @code
 * self = [super init];
 *
 * @try {
 *         // Custom initialization code goes here.
 * } @catch (id e) {
 *         [self release];
 *         @throw e;
 * }
 *
 * return self;
 * @endcode

 *
 * With ARC enabled, the following pattern needs to be used instead:
 * @code
 * self = [super init];
 *
 * // Custom initialization code goes here.
 *
 * return self;
 * @endcode
 *
 * @ref init may never return `nil`, instead an exception (for example
 * @ref OFInitializationFailedException) should be thrown.
 *
 * @return An initialized object
 */
- (instancetype)init;

/*!
 * @brief Returns the method signature for the specified selector.

Modified src/OFStdIOStream.h from [3916cd29d8] to [0fa3bc5f34].

20
21
22
23
24
25
26


27
28
29
30
31
32
33
..
80
81
82
83
84
85
86






87
88
89
90
91
92

#ifdef OF_AMIGAOS
# include <dos/dos.h>
#endif

OF_ASSUME_NONNULL_BEGIN



/*!
 * @class OFStdIOStream OFStdIOStream.h ObjFW/OFStdIOStream.h
 *
 * @brief A class for providing standard input, output and error as OFStream.
 *
 * The global variables @ref of_stdin, @ref of_stdout and @ref of_stderr are
 * instances of this class and need no initialization.
................................................................................
extern OFStdIOStream *_Nullable of_stdout;

/*!
 * @brief The standard error as an OFStream.
 */
extern OFStdIOStream *_Nullable of_stderr;







extern void of_log(OFConstantString *, ...);
#ifdef __cplusplus
}
#endif

OF_ASSUME_NONNULL_END







>
>







 







>
>
>
>
>
>
|





20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
..
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

#ifdef OF_AMIGAOS
# include <dos/dos.h>
#endif

OF_ASSUME_NONNULL_BEGIN

/*! @file */

/*!
 * @class OFStdIOStream OFStdIOStream.h ObjFW/OFStdIOStream.h
 *
 * @brief A class for providing standard input, output and error as OFStream.
 *
 * The global variables @ref of_stdin, @ref of_stdout and @ref of_stderr are
 * instances of this class and need no initialization.
................................................................................
extern OFStdIOStream *_Nullable of_stdout;

/*!
 * @brief The standard error as an OFStream.
 */
extern OFStdIOStream *_Nullable of_stderr;

/*!
 * @brief Log the specified printf-style format to @ref of_stderr.
 *
 * This prefixes the output with the date, timestamp, process name and PID and
 * allows `%@` as a printf-style formatted to print objects.
 */
extern void of_log(OFConstantString *format, ...);
#ifdef __cplusplus
}
#endif

OF_ASSUME_NONNULL_END

Modified src/OFStream.h from [7421ae1300] to [24a98018d3].

243
244
245
246
247
248
249
250


251
252
253
254
255
256
257
...
280
281
282
283
284
285
286
287


288
289
290
291
292
293
294
...
301
302
303
304
305
306
307
308


309
310
311
312
313
314
315
...
365
366
367
368
369
370
371
372


373
374
375
376
377
378
379
...
392
393
394
395
396
397
398
399


400
401
402
403
404
405
406
/*!
 * @brief Reads *at most* size bytes from the stream into a buffer.
 *
 * On network streams, this might read less than the specified number of bytes.
 * If you want to read exactly the specified number of bytes, use
 * @ref readIntoBuffer:exactLength:. Note that a read can even return 0 bytes -
 * this does not necessarily mean that the stream ended, so you still need to
 * check @ref atEndOfStream.


 *
 * @param buffer The buffer into which the data is read
 * @param length The length of the data that should be read at most.
 *		 The buffer *must* be *at least* this big!
 * @return The number of bytes read
 */
- (size_t)readIntoBuffer: (void *)buffer
................................................................................
 * @brief Asynchronously reads *at most* size bytes from the stream into a
 *	  buffer.
 *
 * On network streams, this might read less than the specified number of bytes.
 * If you want to read exactly the specified number of bytes, use
 * @ref asyncReadIntoBuffer:exactLength:. Note that a read can even return 0
 * bytes - this does not necessarily mean that the stream ended, so you still
 * need to check @ref atEndOfStream.


 *
 * @note The stream must conform to @ref OFReadyForReadingObserving in order
 *	 for this to work!
 *
 * @param buffer The buffer into which the data is read.
 *		 The buffer must not be freed before the async read completed!
 * @param length The length of the data that should be read at most.
................................................................................
 * @brief Asynchronously reads *at most* size bytes from the stream into a
 *	  buffer.
 *
 * On network streams, this might read less than the specified number of bytes.
 * If you want to read exactly the specified number of bytes, use
 * @ref asyncReadIntoBuffer:exactLength:. Note that a read can even return 0
 * bytes - this does not necessarily mean that the stream ended, so you still
 * need to check @ref atEndOfStream.


 *
 * @note The stream must conform to @ref OFReadyForReadingObserving in order
 *	 for this to work!
 *
 * @param buffer The buffer into which the data is read.
 *		 The buffer must not be freed before the async read completed!
 * @param length The length of the data that should be read at most.
................................................................................
 * @brief Asynchronously reads *at most* ref size bytes from the stream into a
 *	  buffer.
 *
 * On network streams, this might read less than the specified number of bytes.
 * If you want to read exactly the specified number of bytes, use
 * @ref asyncReadIntoBuffer:exactLength:block:. Note that a read can even
 * return 0 bytes - this does not necessarily mean that the stream ended, so
 * you still need to check @ref atEndOfStream.


 *
 * @note The stream must conform to @ref OFReadyForReadingObserving in order
 *	 for this to work!
 *
 * @param buffer The buffer into which the data is read.
 *		 The buffer must not be freed before the async read completed!
 * @param length The length of the data that should be read at most.
................................................................................
 * @brief Asynchronously reads *at most* ref size bytes from the stream into a
 *	  buffer.
 *
 * On network streams, this might read less than the specified number of bytes.
 * If you want to read exactly the specified number of bytes, use
 * @ref asyncReadIntoBuffer:exactLength:block:. Note that a read can even
 * return 0 bytes - this does not necessarily mean that the stream ended, so
 * you still need to check @ref atEndOfStream.


 *
 * @note The stream must conform to @ref OFReadyForReadingObserving in order
 *	 for this to work!
 *
 * @param buffer The buffer into which the data is read.
 *		 The buffer must not be freed before the async read completed!
 * @param length The length of the data that should be read at most.







|
>
>







 







|
>
>







 







|
>
>







 







|
>
>







 







|
>
>







243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
...
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
...
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
...
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
...
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
/*!
 * @brief Reads *at most* size bytes from the stream into a buffer.
 *
 * On network streams, this might read less than the specified number of bytes.
 * If you want to read exactly the specified number of bytes, use
 * @ref readIntoBuffer:exactLength:. Note that a read can even return 0 bytes -
 * this does not necessarily mean that the stream ended, so you still need to
 * check @ref atEndOfStream. Do not assume that the stream ended just because a
 * read returned 0 bytes - some streams do internal processing that has a
 * result of 0 bytes.
 *
 * @param buffer The buffer into which the data is read
 * @param length The length of the data that should be read at most.
 *		 The buffer *must* be *at least* this big!
 * @return The number of bytes read
 */
- (size_t)readIntoBuffer: (void *)buffer
................................................................................
 * @brief Asynchronously reads *at most* size bytes from the stream into a
 *	  buffer.
 *
 * On network streams, this might read less than the specified number of bytes.
 * If you want to read exactly the specified number of bytes, use
 * @ref asyncReadIntoBuffer:exactLength:. Note that a read can even return 0
 * bytes - this does not necessarily mean that the stream ended, so you still
 * need to check @ref atEndOfStream. Do not assume that the stream ended just
 * because a read returned 0 bytes - some streams do internal processing that
 * has a result of 0 bytes.
 *
 * @note The stream must conform to @ref OFReadyForReadingObserving in order
 *	 for this to work!
 *
 * @param buffer The buffer into which the data is read.
 *		 The buffer must not be freed before the async read completed!
 * @param length The length of the data that should be read at most.
................................................................................
 * @brief Asynchronously reads *at most* size bytes from the stream into a
 *	  buffer.
 *
 * On network streams, this might read less than the specified number of bytes.
 * If you want to read exactly the specified number of bytes, use
 * @ref asyncReadIntoBuffer:exactLength:. Note that a read can even return 0
 * bytes - this does not necessarily mean that the stream ended, so you still
 * need to check @ref atEndOfStream. Do not assume that the stream ended just
 * because a read returned 0 bytes - some streams do internal processing that
 * has a result of 0 bytes.
 *
 * @note The stream must conform to @ref OFReadyForReadingObserving in order
 *	 for this to work!
 *
 * @param buffer The buffer into which the data is read.
 *		 The buffer must not be freed before the async read completed!
 * @param length The length of the data that should be read at most.
................................................................................
 * @brief Asynchronously reads *at most* ref size bytes from the stream into a
 *	  buffer.
 *
 * On network streams, this might read less than the specified number of bytes.
 * If you want to read exactly the specified number of bytes, use
 * @ref asyncReadIntoBuffer:exactLength:block:. Note that a read can even
 * return 0 bytes - this does not necessarily mean that the stream ended, so
 * you still need to check @ref atEndOfStream. Do not assume that the stream
 * ended just because a read returned 0 bytes - some streams do internal
 * processing that has a result of 0 bytes.
 *
 * @note The stream must conform to @ref OFReadyForReadingObserving in order
 *	 for this to work!
 *
 * @param buffer The buffer into which the data is read.
 *		 The buffer must not be freed before the async read completed!
 * @param length The length of the data that should be read at most.
................................................................................
 * @brief Asynchronously reads *at most* ref size bytes from the stream into a
 *	  buffer.
 *
 * On network streams, this might read less than the specified number of bytes.
 * If you want to read exactly the specified number of bytes, use
 * @ref asyncReadIntoBuffer:exactLength:block:. Note that a read can even
 * return 0 bytes - this does not necessarily mean that the stream ended, so
 * you still need to check @ref atEndOfStream. Do not assume that the stream
 * ended just because a read returned 0 bytes - some streams do internal
 * processing that has a result of 0 bytes.
 *
 * @note The stream must conform to @ref OFReadyForReadingObserving in order
 *	 for this to work!
 *
 * @param buffer The buffer into which the data is read.
 *		 The buffer must not be freed before the async read completed!
 * @param length The length of the data that should be read at most.