forked from tomaz/appledoc
/
GBComment.h
200 lines (139 loc) · 8.01 KB
/
GBComment.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
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
//
// GBComment.h
// appledoc
//
// Created by Tomaz Kragelj on 27.8.10.
// Copyright (C) 2010, Gentle Bytes. All rights reserved.
//
#import <Foundation/Foundation.h>
@class GBSourceInfo;
@class GBCommentComponent;
@class GBCommentComponentsList;
/** Handles all comment related stuff.
Each instance describes a single source code comment for any object - class, category, protocol, method... As the comment is universal for each object, it contains properties for all fields applying to any kind of object. However not all are used in all cases. If a property is not used, it's value remains `nil`. Derived values are handled with:
- `shortDescription`: Provides short description of the commented entity used for tooltips and abstract.
- `longDescription`: Provides the whole description of the commented entity. This can include `shortDescription` or not, based on settings.
- `methodParameters`: The list of all method parameters. Only used for methods.
- `methodResult`: Description of method result. Only used for methods.
- `methodExceptions`: The list of all possible exceptions. Only used for methods.
- `availability`: A text representing the version at which this method / property is available. Can also be applied to other entities
- `relatedItems`: The list of all related items. Used for cross referencing other entities.
All lists must be provided in the desired order of output - i.e. output formatters don't apply any sorting, they simply emit the values in the given order.
`GBComment` is not context aware by itself, it's simply a container object that holds comment information. It's the rest of the application that's responsible for setting it's values as needed. In most cases it's `GBParser`s who sets comments string value and `GBProcessor`s to parse string value and setup the derived properties based on the comment's context.
@warning *Note:* Although derived values are prepared based on `stringValue`, nothing prevents clients to setup derived values directly, "on the fly" if needed. However splitting the interface allows us to simplify parsing code and allow us to handle derives values when we have complete information available.
*/
@interface GBComment : NSObject
///---------------------------------------------------------------------------------------
/// @name Initialization & disposal
///---------------------------------------------------------------------------------------
/** Returns a new autoreleased instance of the comment with the given string value.
This is a helper initializer which allows setting string value with a single message. Sending this message is equivalent to sending `commentWithStringValue:sourceInfo:`, passing the given _value_ and `nil` for source info.
@param value String value to set.
@return Returns initialized object or `nil` if initialization fails.
@see commentWithStringValue:sourceInfo:
*/
+ (id)commentWithStringValue:(NSString *)value;
/** Returns a new autoreleased instance of the comment with the given string value and source info.
This is a helper initializer which allows setting default values with a single message.
@param value String value to set.
@param info Source info to set.
@return Returns initialized object or `nil` if initialization fails.
@see commentWithStringValue:
*/
+ (id)commentWithStringValue:(NSString *)value sourceInfo:(GBSourceInfo *)info;
///---------------------------------------------------------------------------------------
/// @name Comment components handling
///---------------------------------------------------------------------------------------
/** Comments short description used for tooltips and abstract in the form of `GBCommentComponent`.
@see longDescription
*/
@property (retain) GBCommentComponent *shortDescription;
/** Comments long description, includes the whole description components.
Depending settings, this may also repeat `shortDescription` or not. `GBComment` assigns default object here, but clients are free to replace it with their own implementations.
@see shortDescription
*/
@property (retain) GBCommentComponentsList *longDescription;
/** The list to related items.
This is simply a list of `GBCommentComponent`s, each one containing a cross reference to a single item.
*/
@property (retain) GBCommentComponentsList *relatedItems;
/** All registered method parameters, only applicable for methods, empty list is used otherwise.
This is a list of `GBCommentArgument` objects.
@see methodExceptions
@see methodResult
*/
@property (retain) NSMutableArray *methodParameters;
/** All registeres method exceptions, only applicable for methods, empty list if used otherwise.
This is a list of `GBCommentArgument` objects.
@see methodParameters
@see methodResult
*/
@property (retain) NSMutableArray *methodExceptions;
/** Method result description, only applicable for methods, empty list is used otherwise.
@see methodParameters
@see methodExceptions
*/
@property (retain) GBCommentComponentsList *methodResult;
/** Entity availability description.
*/
@property (retain) GBCommentComponentsList *availability;
///---------------------------------------------------------------------------------------
/// @name Output generator helpers
///---------------------------------------------------------------------------------------
/** Specifies the original processing context of the comment.
This value points to the context inside which the comment was parsed. The main reason for this is to restrict processing of copied comments within their original context, so that any cross references are properly handled(mainly to suppress unrelated warnings). The value related to the context is:
- Normal comments attached to classes, categories, protocols or methods as found in source code: the value is `nil`.
- Comments assigned to classes, categories or protocols, copied from another class, category or protocol: the value is the pointer to the original object.
- Comments assigned to methods, copied from another method: the value is the pointer to original method's parent.
@see isCopied
*/
@property (assign) id originalContext;
/** Specifies whether the comment is copied from another object or this is the original comment from source code.
The value of this property depends on `originalContext`. If original context is assigned, the value is `YES`, otherwise it's `NO`.
@see originalContext
@see isProcessed
*/
@property (readonly) BOOL isCopied;
/** Specifies whether the comment is already processed or not.
This is used mainly for better support of copied comments!
@see isCopied
*/
@property (assign) BOOL isProcessed;
/** Specifies whether the comment has short description or not.
@see hasLongDescription
*/
@property (readonly) BOOL hasShortDescription;
/** Specifies whether the comment has long description or not.
@see hasShortDescription
*/
@property (readonly) BOOL hasLongDescription;
/** Specifies whether the `methodParameters` contains at least one object or not.
@see hasMethodExceptions
@see hasMethodResult
*/
@property (readonly) BOOL hasMethodParameters;
/** Specifies whether the `methodExceptions` contains at least one object or not.
@see hasMethodParameters
@see hasMethodResult
*/
@property (readonly) BOOL hasMethodExceptions;
/** Specifies whether the `methodResult` contains at least one object or not.
@see hasMethodParameters
@see hasMethodExceptions
*/
@property (readonly) BOOL hasMethodResult;
/** Specifies whether the `availability` contains at least one object or not.
@see availability
*/
@property (readonly) BOOL hasAvailability;
/** Specifies whether the `relatedItems` contains at least one object or not.
*/
@property (readonly) BOOL hasRelatedItems;
///---------------------------------------------------------------------------------------
/// @name Input values
///---------------------------------------------------------------------------------------
/** Comment's source file info. */
@property (retain) GBSourceInfo *sourceInfo;
/** Comment's raw string value as declared in source code. */
@property (copy) NSString *stringValue;
@end