Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 82 lines (58 sloc) 5.035 kB
c5ef141 @tomaz Refactored list items handling to be prepared for nested lists.
authored
1 //
2 // GBCommentsProcessor.h
3 // appledoc
4 //
5 // Created by Tomaz Kragelj on 27.8.10.
6 // Copyright (C) 2010, Gentle Bytes. All rights reserved.
7 //
8
9 #import <Foundation/Foundation.h>
10
11 @class GBComment;
12
13 /** Implements comments processing.
14
15 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.
16 */
17 @interface GBCommentsProcessor : NSObject
18
19 ///---------------------------------------------------------------------------------------
20 /// @name Initialization & disposal
21 ///---------------------------------------------------------------------------------------
22
23 /** Returns autoreleased processor to work with the given `GBApplicationSettingsProvider` implementor.
24
25 This is the designated initializer.
26
27 @param settingsProvider Application-wide settings provider to use for checking parameters.
28 @return Returns initialized instance or `nil` if initialization fails.
29 @exception NSException Thrown if the given application is `nil`.
30 */
31 + (id)processorWithSettingsProvider:(id)settingsProvider;
32
33 /** Initializes the processor to work with the given `GBApplicationSettingsProvider` implementor.
34
35 This is the designated initializer.
36
37 @param settingsProvider Application-wide settings provider to use for checking parameters.
38 @return Returns initialized instance or `nil` if initialization fails.
39 @exception NSException Thrown if the given application is `nil`.
40 */
41 - (id)initWithSettingsProvider:(id)settingsProvider;
42
43 ///---------------------------------------------------------------------------------------
44 /// @name Processing handling
45 ///---------------------------------------------------------------------------------------
46
1cff516 @tomaz Self references don't form links. Closes #190.
authored
47 /** Processes the comment of the given object using the given context and store.
48
49 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!
50
51 @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.
52
53 @param comment The comment to process.
54 @param context The object identifying current context for handling links or `nil`.
55 @param store The store to process against.
56 @exception NSException Thrown if any of the given parameters is invalid or processing encounters unexpected error.
57 @see alwaysRepeatFirstParagraph
58 */
59 - (void)processCommentForObject:(GBModelBase *)object withContext:(id)context store:(id)store;
60
c5ef141 @tomaz Refactored list items handling to be prepared for nested lists.
authored
61 /** Processes the given `GBComment` using the given context and store.
62
63 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!
64
65 @param comment The comment to process.
0e6beb1 @tomaz Implemented searching for next comment block within comment source st…
authored
66 @param context The object identifying current context for handling links or `nil`.
c5ef141 @tomaz Refactored list items handling to be prepared for nested lists.
authored
67 @param store The store to process against.
68 @exception NSException Thrown if any of the given parameters is invalid or processing encounters unexpected error.
e2c8832 @tomaz Fixed warnings due to invalid cross references in various comments.
authored
69 @see alwaysRepeatFirstParagraph
c5ef141 @tomaz Refactored list items handling to be prepared for nested lists.
authored
70 */
0e6beb1 @tomaz Implemented searching for next comment block within comment source st…
authored
71 - (void)processComment:(GBComment *)comment withContext:(id)context store:(id)store;
c5ef141 @tomaz Refactored list items handling to be prepared for nested lists.
authored
72
c4f799b @tomaz Fixed `--repeat-first-par` option handling for methods.
authored
73 /** Specifies whether first paragraph should be repeated or not regardless of settings.
c5ef141 @tomaz Refactored list items handling to be prepared for nested lists.
authored
74
c4f799b @tomaz Fixed `--repeat-first-par` option handling for methods.
authored
75 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.
c5ef141 @tomaz Refactored list items handling to be prepared for nested lists.
authored
76
77 @see processComment:withContext:store:
78 */
c4f799b @tomaz Fixed `--repeat-first-par` option handling for methods.
authored
79 @property (assign) BOOL alwaysRepeatFirstParagraph;
c5ef141 @tomaz Refactored list items handling to be prepared for nested lists.
authored
80
81 @end
Something went wrong with that request. Please try again.