-
Notifications
You must be signed in to change notification settings - Fork 644
/
GBCommentsProcessor.h
81 lines (58 loc) · 4.92 KB
/
GBCommentsProcessor.h
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
//
// GBCommentsProcessor.h
// appledoc
//
// Created by Tomaz Kragelj on 27.8.10.
// Copyright (C) 2010, Gentle Bytes. All rights reserved.
//
#import <Foundation/Foundation.h>
@class GBComment;
/** Implements comments processing.
The main responsibility of this class is to process comments. As it's a helper class for `GBProcessor`, it's processing is driven by the processor, so there's no need to create instances elsewhere.
*/
@interface GBCommentsProcessor : NSObject
///---------------------------------------------------------------------------------------
/// @name Initialization & disposal
///---------------------------------------------------------------------------------------
/** Returns autoreleased processor to work with the given `GBApplicationSettingsProvider` implementor.
This is the designated initializer.
@param settingsProvider Application-wide settings provider to use for checking parameters.
@return Returns initialized instance or `nil` if initialization fails.
@exception NSException Thrown if the given application is `nil`.
*/
+ (id)processorWithSettingsProvider:(id)settingsProvider;
/** Initializes the processor to work with the given `GBApplicationSettingsProvider` implementor.
This is the designated initializer.
@param settingsProvider Application-wide settings provider to use for checking parameters.
@return Returns initialized instance or `nil` if initialization fails.
@exception NSException Thrown if the given application is `nil`.
*/
- (id)initWithSettingsProvider:(id)settingsProvider;
///---------------------------------------------------------------------------------------
/// @name Processing handling
///---------------------------------------------------------------------------------------
/** Processes the comment of the given object using the given context and store.
This method processes the given comment's string value and prepares all derives values. It uses the given store for dependent values such as links and similar, so make sure the store has all possible objects already registered. In order to properly handle "local" links, the method also takes `context` parameter which identifies top-level object to which the object which's comment we're processing belongs to. You can pass `nil` however this prevents any local links being processed!
@warning **Important:** Note that this method is similar to `processComment:withContext:store:`, in fact, the only difference is that it stores the given object to internal property and then sends `processComment:withContext:store:` to receiver. The big difference is that this method prevents forming cross references to current member, while `processComment:withContext:store:` doesn't. Therefore, this is preffered method for processing comments. The only reasong for keeping two methods is due to unit tests relying on `processComment:withContext:store:` - as that was previously the entry point for processing, all unit tests use it and I don't want to update all of them. So the quick fix was to introduce another method, make sure it gets called from other parts of the tool and keep it as simple as possible.
@param comment The comment to process.
@param context The object identifying current context for handling links or `nil`.
@param store The store to process against.
@exception NSException Thrown if any of the given parameters is invalid or processing encounters unexpected error.
@see alwaysRepeatFirstParagraph
*/
- (void)processCommentForObject:(GBModelBase *)object withContext:(id)context store:(id)store;
/** Processes the given `GBComment` using the given context and store.
This method processes the given comment's string value and prepares all derives values. It uses the given store for dependent values such as links and similar, so make sure the store has all possible objects already registered. In order to properly handle "local" links, the method also takes `context` parameter which identifies top-level object to which the object which's comment we're processing belongs to. You can pass `nil` however this prevents any local links being processed!
@param comment The comment to process.
@param context The object identifying current context for handling links or `nil`.
@param store The store to process against.
@exception NSException Thrown if any of the given parameters is invalid or processing encounters unexpected error.
@see alwaysRepeatFirstParagraph
*/
- (void)processComment:(GBComment *)comment withContext:(id)context store:(id)store;
/** Specifies whether first paragraph should be repeated or not regardless of settings.
This is used for top level objects and static documents where we want to include full comment text regardless of the settings. In that situation we need to set this flag to `YES` to override settings, however for methods we must set this flag to `NO` to respect user's settings.
@see processComment:withContext:store:
*/
@property (assign) BOOL alwaysRepeatFirstParagraph;
@end