Skip to content
Newer
Older
100644 249 lines (211 sloc) 10.6 KB
3a46c43 @tomaz Refactored output generation by moving all specifics to OutputGenerat…
authored Jun 12, 2009
1 //
2 // XMLBasedOutputGenerator.h
3 // appledoc
4 //
5 // Created by Tomaz Kragelj on 28.5.09.
6 // Copyright (C) 2009, Tomaz Kragelj. All rights reserved.
7 //
8
9 #import "OutputGenerator.h"
10
11 /** Defines different object info item types. */
12 enum TKGeneratorObjectInfoItemTypes
13 {
14 kTKObjectInfoItemInherits,
15 kTKObjectInfoItemConforms,
16 kTKObjectInfoItemDeclared,
17 };
18
19 /** Defines different object main member group types. */
20 enum TKGeneratorObjectMemberTypes
21 {
22 kTKObjectMemberTypeClass,
23 kTKObjectMemberTypeInstance,
24 kTKObjectMemberTypeProperty,
25 };
26
27 /** Defines different object member prototype item types. These values define the type
28 of the item which can either be value or parameter name. */
29 enum TKGeneratorObjectPrototypeTypes
30 {
31 kTKObjectMemberPrototypeValue,
32 kTKObjectMemberPrototypeParameter,
33 };
34
35 /** Defines different object common member section types. These are used mainly to
36 simplify the code and avoid repetition since many member sections use the same layout
37 for different types of sections. */
38 enum TKGeneratorObjectMemberSectionTypes
39 {
40 kTKObjectMemberSectionParameters,
41 kTKObjectMemberSectionExceptions,
42 };
43
26c268f @tomaz Refactored description blocks documentation extraction.
authored Jun 18, 2009
44 /** Defines different description item types. Description item types are used when
45 appending brief or detailed description. */
46 enum TKGeneratorDescriptionItemTypes
47 {
48 kTKDescriptionParagraphStart,
49 kTKDescriptionParagraphEnd,
50 kTKDescriptionCodeStart,
51 kTKDescriptionCodeEnd,
52 kTKDescriptionListStart,
53 kTKDescriptionListEnd,
54 kTKDescriptionListItemStart,
55 kTKDescriptionListItemEnd,
56 kTKDescriptionStrongStart,
57 kTKDescriptionStrongEnd,
58 kTKDescriptionEmphasisStart,
59 kTKDescriptionEmphasisEnd,
60 kTKDescriptionExampleStart,
61 kTKDescriptionExampleEnd,
62 kTKDescriptionReferenceStart,
63 kTKDescriptionReferenceEnd,
64 kTKDescriptionText,
65 };
66
3a46c43 @tomaz Refactored output generation by moving all specifics to OutputGenerat…
authored Jun 12, 2009
67 /** Defines different index group types. These are used mainly to simplify the code and
26c268f @tomaz Refactored description blocks documentation extraction.
authored Jun 18, 2009
68 avoid repetition since all of the groups use the same layout. */
3a46c43 @tomaz Refactored output generation by moving all specifics to OutputGenerat…
authored Jun 12, 2009
69 enum TKGeneratorIndexGroupTypes
70 {
71 kTKIndexGroupClasses,
72 kTKIndexGroupProtocols,
73 kTKIndexGroupCategories,
74 };
75
76 //////////////////////////////////////////////////////////////////////////////////////////
77 //////////////////////////////////////////////////////////////////////////////////////////
78 /** Defines the basics for a concrete @c OutputGenerator which is based on the
79 output produces by @c XMLOutputGenerator.
80
81 The main responsibility of this class is to hide the underlying XML handling from the
82 subclasses. Instead it delegates parsing of the underlying data by sending the subclass
83 messages for each detected data and by providing several utility methods that can be used
84 to extract the data from the arguments. This unifies parsing for all subclasses and allows
85 one-point handling for each different value, so if XML structure changes one day, there
86 should be very small ammount of work for subclasses.
87
88 Each concrete subclass can convert three types of files - index, hierarchy and object files.
89 The subclass can only override the methods for generating output that makes sense for the
90 implemented output type. The @c XMLBasedOutputGenerator overrides the
04e7189 @tomaz Fixed code documentation in XMLBasedOutputGenerator and updated log m…
authored Jun 12, 2009
91 @c generateSpecificOutput() in which it delegates the concrete output generation through
3a46c43 @tomaz Refactored output generation by moving all specifics to OutputGenerat…
authored Jun 12, 2009
92 the following messages:
93 - @c generateOutputForIndex() to generate the main index file,
94 - @c generateOutputForHierarchy() to generate the main hierarchy file and
95 - @c generateOutputForObject:() to generate the documentation for each individual object.
96
97 However the subclass should not override these, but instead override all associated
98 @c append______ methods (see the documentation for above mentioned methods for details).
99 The main responsibility of these entry points is to setup data and invoke parsing of the
100 associated XML structure which ends in @c append______ being sent. The subclass should
101 override these and handle the data as needed. To extract the usable information from
102 each append method, @c extract______ messages can be sent to the receiver. Additionaly,
103 subclasses should also handle the rest of the @c OutputGenerator tasks such as creation
104 and removal of output directories etc.
105
106 @warning @b Important: Note that @c outputGenerationStarting() is used to setup internal
107 state, so in case subclass needs to override it, base implementation needs to be
108 called!
109 */
110 @interface XMLBasedOutputGenerator : OutputGenerator
111 {
112 NSDictionary* objectData;
113 NSXMLDocument* objectMarkup;
114 NSXMLDocument* indexMarkup;
115 NSXMLDocument* hierarchyMarkup;
116 BOOL outputFileWasCreated;
117 }
118
119 //////////////////////////////////////////////////////////////////////////////////////////
120 /// @name Generation entry points
121 //////////////////////////////////////////////////////////////////////////////////////////
122
123 /** Generates the output data for the given object data from the main database.
124
125 This message is sent from @c generateSpecificOutput() after the passed object data
126 is stored in the class properties. The concrete subclasses that require full control over
127 the generated data, can override this method and return the desired output. If overriden,
128 the subclass can get the XML document through the @c objectMarkup property.
129
130 By default, this will send several higher level messages which can be overriden instead.
131 This is the recommended way of handling the output generation. The messages are sent in
132 the following order:
133 - @c appendObjectHeaderToData:()
134 - @c appendObjectInfoHeaderToData:() @a *
135 - @c appendObjectInfoItemToData:fromItems:index:type:() @a **
136 - @c appendObjectInfoFooterToData:() @a *
137 - @c appendObjectOverviewToData:fromItem:() @a *
138 - @c appendObjectTasksHeaderToData:() @a *
139 - @c appendObjectTaskHeaderToData:fromItem:index:() @a **
140 - @c appendObjectTaskMemberToData:fromItem:index:() @a **
141 - @c appendObjectTaskFooterToData:fromItem:index:() @a **
142 - @c appendObjectTasksFooterToData:() @a *
143 - @c appendObjectMembersHeaderToData:() @a *
144 - @c appendObjectMemberGroupHeaderToData:type:() @a **
145 - @c appendObjectMemberToData:fromItem:index:() @a **
146 - @c appendObjectMemberGroupFooterToData:type:() @a **
147 - @c appendObjectMembersFooterToData:() @a *
148 - @c appendObjectFooterToData:()
149
150 Note that only a subset of above messages may be sent for a particular object, depending
151 on the object data. Messages marked with @a * are optional, while messages marked with
152 @a ** may additionaly be sent multiple times, for each corresponding item once.
153
154 After generation finishes, the corresponding file is saved to the proper location.
155
156 @param data The object @c NSDictionary from the main database.
157 @exception NSException Thrown if the given data is @c nil or generation fails.
158 @see generateOutputForIndex
159 @see generateOutputForHierarchy
160 */
161 - (void) generateOutputForObject:(NSDictionary*) data;
162
163 /** Generates the output data for the main index.
164
165 This message is sent from @c generateSpecificOutput() after the objects generation
166 finishes. The concrete subclasses that require full control over the generated data, can
167 override this method and return the desired output. If overriden, the subclass can get
168 the clean index XML data through the @c indexMarkup() property.
169
170 By default, this will send several higher level messages which can be overriden instead.
171 This is the recommended way of handling the output generation. The messages are sent in
172 the following order:
173 - @c appendIndexHeaderToData:()
174 - @c appendIndexGroupHeaderToData:type:() **
175 - @c appendIndexGroupItemToData:fromItem:index:type:() **
176 - @c appendIndexGroupFooterToData:type:() **
177 - @c appendIndexFooterToData:()
178
179 Note that only a subset of above messages may be sent for a particular object, depending
180 on the object data. Messages marked with @a * are optional, while messages marked with
181 @a ** may additionaly be sent multiple times, for each corresponding item once.
182
183 After generation finishes, the corresponding file is saved to the proper location.
184
185 @exception NSException Thrown if the generation fails.
186 @see generateOutputForObject:
187 @see generateOutputForHierarchy
188 */
189 - (void) generateOutputForIndex;
190
191 /** Generates the output data from the data contained in the class properties.
192
193 This message is sent from @c generateSpecificOutput() after the objects and index
194 generation finishes. The concrete subclasses that require full control over the
195 generated data, can override this method and return the desired output. If overriden,
196 the subclass can get the clean hierarchy XML through the @c hierarchyMarkup() property.
197
198 By default, this will send several higher level messages which can be overriden instead.
199 This is the recommended way of handling the output generation. The messages are sent in
200 the following order:
201 - @c appendHierarchyHeaderToData:()
202 - @c appendHierarchyGroupHeaderToData:() **
203 - @c appendHierarchyGroupItemToData:fromItem:index:() **
204 - @c appendHierarchyGroupFooterToData:() **
205 - @c appendHierarchyFooterToData:()
206
207 Note that only a subset of above messages may be sent for a particular object, depending
208 on the object data. Messages marked with @a * are optional, while messages marked with
209 @a ** may additionaly be sent multiple times, for each corresponding item once.
210
211 @warning @b Important: Since objects hierarchy is tree-like structure with multiple levels,
212 subclass should be able to have full control of when the children of a particular item
213 are handled. The base class only automates the root objects notifications, while the
214 subclass is responsible for sending @c generateHierarchyGroupChildrenToData:forItem:()
215 from within it's @c appendHierarchyGroupItemToData:fromItem:index:() override in order
216 to trigger the parsing of the children (if there are some). This deviates somehow from
217 the rest of the output generation types. This actually starts recursive loop between
218 @c generateHierarchyGroupChildrenToData:forItem:() and
219 @c appendHierarchyGroupItemToData:fromItem:index:(), however do not fear, since the
220 base class method will automatically stop when no more children are detected.
221 @exception NSException Thrown if the given @c data or saving to file fails.
222 @see generateOutputForObject:
223 @see generateOutputForIndex
224 */
225 - (void) generateOutputForHierarchy;
226
227 //////////////////////////////////////////////////////////////////////////////////////////
228 /// @name Properties
229 //////////////////////////////////////////////////////////////////////////////////////////
230
231 /** Returns the project name from command line. */
232 @property(readonly) NSString* projectName;
233
234 /** Returns the last updated date formatted in standard way.
235
236 Note that this always return formatted current system time.
237 */
238 @property(readonly) NSString* lastUpdated;
239
240 /** Returns the status of output files generation.
241
242 This returns @c YES if at least one output file was generated within the last generation
04e7189 @tomaz Fixed code documentation in XMLBasedOutputGenerator and updated log m…
authored Jun 12, 2009
243 run (i.e. between the @c outputGenerationStarting() and @c outputGenerationFinished()
244 messages).
3a46c43 @tomaz Refactored output generation by moving all specifics to OutputGenerat…
authored Jun 12, 2009
245 */
246 @property(readonly) BOOL outputFileWasCreated;
247
248 @end
Something went wrong with that request. Please try again.