Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 656 lines (456 sloc) 36.284 kB
7d6a323 @tomaz Copied all the changes from the old generating branch.
authored
1 //
2 // GBApplicationSettingsProvider.h
3 // appledoc
4 //
5 // Created by Tomaz Kragelj on 3.10.10.
6 // Copyright (C) 2010, Gentle Bytes. All rights reserved.
7 //
8
1586e38 @tomaz Refactored settings handling by removing GBApplicationSettingsProvidi…
authored
9 #import "GBCommentComponentsProvider.h"
10 #import "GBApplicationStringsProvider.h"
11
12 @class GBModelBase;
7d6a323 @tomaz Copied all the changes from the old generating branch.
authored
13
7d18569 @tomaz Implemented possibility of injecting descriptions to main index file.…
authored
14 extern id kGBCustomDocumentIndexDescKey;
15
16 #pragma mark -
17
7d6a323 @tomaz Copied all the changes from the old generating branch.
authored
18 /** Main application settings provider.
19
20 This object implements `GBApplicationStringsProviding` interface and is used by `GBAppledocApplication` to prepare application-wide settings including factory defaults, global and session values. The main purpose of the class is to simplify `GBAppledocApplication` class by decoupling it from the actual settings providing implementation.
1ab0711 @tomaz Added developers check list for creating new command line switches.
authored
21
22 To create a new setting use the following check list to update `GBApplicationSettingsProvider`:
23
24 1. Create the property here (don't forget about `@synthetize`!).
25 2. Set default value in initializer.
26
27 If the setting should be mapped to command line switch also do the following in `GBAppledocApplication`:
28
29 1. Create a new global string as `static NSString` containing the command line switch name.
30 2. Register the switch to `DDCli` (add negated switch if it's a boolean).
ee93385 @tomaz Refined exit codes handling. Closes #102.
authored
31 3. Add unit test in `GBApplicationTesting.m` that validates the switch is properly mapped to setting property (note that boolean switches require testing normal and negated variants!).
1ab0711 @tomaz Added developers check list for creating new command line switches.
authored
32 4. Add KVC setter and map to corresponding property to make the test pass (again booleans require two setters).
33 5. If the switch value uses template placeholders, add unit test in `GBApplicationSettingsProviderTesting.m` that validates the switch is handled.
34 6. If previous point was used, add the code to `replaceAllOccurencesOfPlaceholderStringsInSettingsValues` to make the test pass.
35 7. Add the switch value printout to `printSettingsAndArguments:`.
36 8. Add the switch help printout to `printHelp`.
7d6a323 @tomaz Copied all the changes from the old generating branch.
authored
37 */
a422865 @tomaz Removed GBApplicationSettingsProvider NSCopying.
authored
38 @interface GBApplicationSettingsProvider : NSObject
7d6a323 @tomaz Copied all the changes from the old generating branch.
authored
39
40 ///---------------------------------------------------------------------------------------
41 /// @name Initialization & disposal
42 ///---------------------------------------------------------------------------------------
43
44 /** Returns autoreleased instance of the class.
45 */
46 + (id)provider;
47
1586e38 @tomaz Refactored settings handling by removing GBApplicationSettingsProvidi…
authored
48 ///---------------------------------------------------------------------------------------
49 /// @name Project values handling
50 ///---------------------------------------------------------------------------------------
51
52 /** Human readable name of the project. */
53 @property (copy) NSString *projectName;
54
55 /** Human readable name of the project company. */
56 @property (copy) NSString *projectCompany;
57
58 /** Human readable version of the project. */
59 @property (copy) NSString *projectVersion;
60
61 /** Company unique identifier, ussualy in the form of reverse domain like _com.company_. */
62 @property (copy) NSString *companyIdentifier;
63
afef3b2 @tomaz Implemented proper docset packaging handling. Relates to #45.
authored
64 /** Project identifier which is derived by normalizing `projectName`. */
65 @property (readonly) NSString *projectIdentifier;
66
67 /** Version identifier which is derived by normalizing `projectVersion`. */
68 @property (readonly) NSString *versionIdentifier;
69
1586e38 @tomaz Refactored settings handling by removing GBApplicationSettingsProvidi…
authored
70 ///---------------------------------------------------------------------------------------
71 /// @name Documentation set handling
72 ///---------------------------------------------------------------------------------------
73
74 /** Documentation set bundle identifier. */
75 @property (copy) NSString *docsetBundleIdentifier;
76
77 /** Documentation set bundle name. */
78 @property (copy) NSString *docsetBundleName;
79
80 /** Documentation set certificate issuer. */
81 @property (copy) NSString *docsetCertificateIssuer;
82
83 /** Documentation set certificate signer. */
84 @property (copy) NSString *docsetCertificateSigner;
85
86 /** Documentation set description. */
87 @property (copy) NSString *docsetDescription;
88
89 /** Documentation set fallback URL. */
90 @property (copy) NSString *docsetFallbackURL;
91
92 /** Documentation set feed name. */
93 @property (copy) NSString *docsetFeedName;
94
95 /** Documentation set feed URL. */
96 @property (copy) NSString *docsetFeedURL;
97
895b881 @tomaz Fixed published atom file handling. Closes #45.
authored
98 /** Documentation set package URL. */
99 @property (copy) NSString *docsetPackageURL;
100
1586e38 @tomaz Refactored settings handling by removing GBApplicationSettingsProvidi…
authored
101 /** Documentation set minimum Xcode version. */
102 @property (copy) NSString *docsetMinimumXcodeVersion;
103
f53b1aa @tomaz Fixed Xcode quick help. Fixes #217.
authored
104 /** Documentation set platform family for using within Dash. */
105 @property (copy) NSString *dashDocsetPlatformFamily;
106
1586e38 @tomaz Refactored settings handling by removing GBApplicationSettingsProvidi…
authored
107 /** Documentation set platform family. */
108 @property (copy) NSString *docsetPlatformFamily;
109
110 /** Documentation set publisher identifier. */
111 @property (copy) NSString *docsetPublisherIdentifier;
112
113 /** Documentation set publisher name. */
114 @property (copy) NSString *docsetPublisherName;
115
116 /** Documentation set human readble copyright message. */
117 @property (copy) NSString *docsetCopyrightMessage;
118
afef3b2 @tomaz Implemented proper docset packaging handling. Relates to #45.
authored
119 /** The name of the documentation set installed bundle. The folder is generated in `docsetInstallPath`. */
120 @property (copy) NSString *docsetBundleFilename;
121
122 /** The name of the documentation set atom file when generating publishing files. The file is generated in `outputPath`. */
123 @property (copy) NSString *docsetAtomFilename;
124
125 /** The name of the documentation set compressed package file when generating publishing files. The file is generated in `outputPath`. */
126 @property (copy) NSString *docsetPackageFilename;
127
1586e38 @tomaz Refactored settings handling by removing GBApplicationSettingsProvidi…
authored
128 ///---------------------------------------------------------------------------------------
129 /// @name Paths handling
130 ///---------------------------------------------------------------------------------------
131
132 /** The base path to template files used for generating various output files. */
133 @property (copy) NSString *templatesPath;
134
135 /** The base path of the generated files. */
136 @property (copy) NSString *outputPath;
137
138 /** The path to which documentation set is to be installed. */
139 @property (copy) NSString *docsetInstallPath;
140
141 /** The path to `docsetutil` tool, including tool filename. */
142 @property (copy) NSString *docsetUtilPath;
143
97db241 @tomaz Implemented possibility to add arbitrary documentation. Closes #7.
authored
144 /** The list of all include paths containing static documentation.
145
146 The array contains full paths to either directories or files. In the first case, directories are recursively parsed for all template files (i.e. files with names ending with `-template` and arbitrary extension). Each file is processed the same as any other comment! All non-template files are simply copied over to destination without processing, preserving original directory structure. If the path represents a file, the same logic is applied: if it's a template file it's processed, otherwise it's simply copied over to destination unmodified.
147
148 @warning *Note:* All include paths are copied over to destination defined with `outputPath`, inside `docs` directory. If a path represents a directory, it's copied into a subdirectory of `docs` using the last path component name as the subdirectory name. For example: contents of `some/path/to/dir` would be copied to `docs/dir` within `outputPath` and `another/path` would be copied to `docs/path`. In case the path represents a file, it's simply copied inside `docs` directory at `outputPath`.
149
150 @warning *Important:* Make sure no duplicate directories or files are added to the list - appledoc will fail in such case! Also make sure to not add subpaths of an already added path - this will also fail while copying files!
7d18569 @tomaz Implemented possibility of injecting descriptions to main index file.…
authored
151
152 @see indexDescriptionPath
97db241 @tomaz Implemented possibility to add arbitrary documentation. Closes #7.
authored
153 */
154 @property (retain) NSMutableSet *includePaths;
155
7d18569 @tomaz Implemented possibility of injecting descriptions to main index file.…
authored
156 /** The path to the source file used for injection into autogenerated main index html.
157
158 If this is valid value, pointing to an existing file, it's used to inject the contents of the file into autogenerated main index html. The source file is preprocessed using the same rules as all other static documents.
159
160 @see includePaths
161 */
162 @property (copy) NSString *indexDescriptionPath;
163
1586e38 @tomaz Refactored settings handling by removing GBApplicationSettingsProvidi…
authored
164 /** The list of all full or partial paths to be ignored.
165
166 It's recommended to check if a path string ends with any of the given paths before processing it. This should catch directory and file names properly as directories are processed first.
167 */
97db241 @tomaz Implemented possibility to add arbitrary documentation. Closes #7.
authored
168 @property (retain) NSMutableSet *ignoredPaths;
1586e38 @tomaz Refactored settings handling by removing GBApplicationSettingsProvidi…
authored
169
e0f477a @lhunath Added support for excluding paths from the output.
lhunath authored
170 /** The list of all full or partial paths to exclude from output generation.
171
172 Source code in these paths is still parsed and possibly used for copying to classes not in the excludeOutputPaths.
173 */
174 @property (retain) NSMutableSet *excludeOutputPaths;
175
1586e38 @tomaz Refactored settings handling by removing GBApplicationSettingsProvidi…
authored
176 ///---------------------------------------------------------------------------------------
177 /// @name Behavior handling
178 ///---------------------------------------------------------------------------------------
179
83fb2ff @tomaz Fixed manual property getters and setters handling. Closes #75.
authored
180 /** Indicates whether HTML files should be generated or not.
a28b2ff @tomaz Implemented preparing for docset publishing. Closes #45.
authored
181
182 If `YES`, HTML files are generated in `outputPath` from parsed and processed data. If `NO`, input files are parsed and processed, but nothing is generated.
183
184 @see createDocSet
185 */
186 @property (assign) BOOL createHTML;
187
188 /** Specifies whether documentation set should be created from the HTML files.
189
190 If `YES`, HTML files from html subdirectory in `outputPath` are moved to proper subdirectory within docset output files, then helper files are generated from parsed data. Documentation set files are also indexed. If `NO`, HTML files are left in the output path.
191
d6b842b @tomaz Fixed comment warnings for various objects.
authored
192 @see createHTML
a28b2ff @tomaz Implemented preparing for docset publishing. Closes #45.
authored
193 @see installDocSet
194 @see publishDocSet
195 */
196 @property (assign) BOOL createDocSet;
197
198 /** Specifies whether the documentation set should be installed or not.
199
200 If `YES`, temporary files used for indexing and removed, then documentation set bundle is created from the files from docset output path and is moved to `docsetInstallPath`. If `NO`, all documentation set files are left in output path.
201
202 @see createDocSet
203 @see publishDocSet
204 */
205 @property (assign) BOOL installDocSet;
206
207 /** Specifies whether the documentation set should be prepared for publishing or not.
208
209 If `YES`, installed documentation set is packaged for publishing - an atom feed is created and documentation set is archived. If the atom feed file is alreay found, it is updated with new information. Both, the feed and archived docset files are located within `outputPath`. If `NO`, documentation set is not prepared for publishing.
210
211 @see createDocSet
212 @see installDocSet
213 */
214 @property (assign) BOOL publishDocSet;
215
216 /** Specifies whether intermediate files should be kept in `outputPath` or not.
217
218 If `YES`, all intermediate files (i.e. HTML files and documentation set files) are kept in output path. If `NO`, only final results are kept. This setting not only affects how the files are being handled, it also affects performance. If intermediate files are not kept, appledoc moves files between various generation phases, otherwise it copies them. So it's prefferable to leave this option to `NO`. This option only affects output files, input source files are always left intact!
1edaeab @tomaz Implemented message file generation when installing documentation set…
authored
219
220 @see cleanupOutputPathBeforeRunning
a28b2ff @tomaz Implemented preparing for docset publishing. Closes #45.
authored
221 */
222 @property (assign) BOOL keepIntermediateFiles;
223
1edaeab @tomaz Implemented message file generation when installing documentation set…
authored
224 /** Specifies whether contents of output path should be deleted befor running the tool.
225
226 This is useful to have output path only contain files generated by latest run instead of keeping previous files. Although appledoc removes existing files when needed, it leaves any file or directory that's not touched by this run. So if we created docset in previous run, and only html in current one, the output would contain both subdirs - the fresh HTML files and documentation set from the previous run. Using this option cleans up output path before running so we can start fresh and prevent confusion.
227
228 @see keepIntermediateFiles
229 */
230 @property (assign) BOOL cleanupOutputPathBeforeRunning;
231
efce669 @tomaz Implemented optional disabling of first paragraph repeat for members.…
authored
232 /** Indicates whether the first paragraph needs to be repeated within method and property description or not.
233
234 If `YES`, first paragraph is repeated in members description, otherwise not.
235 */
236 @property (assign) BOOL repeatFirstParagraphForMemberDescription;
237
2e063c0 @tomaz Cleaned up HeaderDoc parsing code and made it optional. References #9…
authored
238 /** Indicates whether we should preprocess header doc style comments or not.
239
240 If `YES`, appledoc will try to do best to handle header doc comments while preprocessing.
241 */
242 @property (assign) BOOL preprocessHeaderDoc;
243
bc892fc @jerryhjones Add support for @note tags.
jerryhjones authored
244 /** Indicates whether we should prepend the name of an information block before the comment
245
246 If `YES`, appledoc will add "Warning: " to the text of a warning informationg block, "Note: " to note blocks, and "Bug: " to bug blocks.
247 */
248 @property (assign) BOOL printInformationBlockTitles;
249
e81e2f8 @tomaz Fixed usage of single star as bold marker (kind of). Closes #154.
authored
250 /** Indicates whether we should treat single stars as bold markers or not.
251
252 If `YES`, single star markers (`*text*`) should be treated as bold markers (`**text**`), otherwise not. This is mainly used for backwards compatibility, but should be disabled as it can cause unexpected issues, such as converting unordered lists into bold etc.
253 */
254 @property (assign) BOOL useSingleStarForBold;
255
e2c8832 @tomaz Fixed warnings due to invalid cross references in various comments.
authored
256 /** Indicates whether undocumented classes, categories or protocols should be kept or ignored when generating output.
1586e38 @tomaz Refactored settings handling by removing GBApplicationSettingsProvidi…
authored
257
258 If `YES` undocumented objects are kept and are used for output generation. If `NO`, these objects are ignored, but only if all their members are also not documented - as soon as a single member is documented, the object is included in output together with all of it's documented members.
259
260 @warning *Note:* Several properties define how undocumented objects are handled: `keepUndocumentedObjects`, `keepUndocumentedMembers` and `findUndocumentedMembersDocumentation`. To better understand how these work together, this is the workflow used when processing parsed objects, prior than passing them to output generators:
261
262 1. If `findUndocumentedMembersDocumentation` is `YES`, all undocumented methods and properties documentation is searched for in known super class hierarchy. If documentation is found in any of the super classes, it is copied to inherited member as well. If `findUndocumentedMembersDocumentation` is `NO`, members are left undocumented and are handled that way in next steps.
263 2. If `keepUndocumentedMembers` is `NO`, all parsed objects' members are iterated over. Any undocumented method or property is removed from class (of course any documentation copied over from super classes in previous step is considered valid too). If `keepUndocumentedMembers` is `NO`, all members are left and if `warnOnUndocumentedMembers` is `YES`, warnings are logged for all undocumented members.
264 3. If `keepUndocumentedObjects` is `NO`, all undocumented classes, categories and protocols that have no documented method or property are also removed. If `keepUndocumentedObjects` is `NO`, all objects are left in the store and are used for output generation and if `warnOnUndocumentedObject` is `YES`, warnings are logged for all undocumented objects.
265
266 @see keepUndocumentedMembers
267 @see findUndocumentedMembersDocumentation;
268 @see warnOnUndocumentedObject
269 */
270 @property (assign) BOOL keepUndocumentedObjects;
271
e2c8832 @tomaz Fixed warnings due to invalid cross references in various comments.
authored
272 /** Indicates whether undocumented methods or properties should be processed or not.
1586e38 @tomaz Refactored settings handling by removing GBApplicationSettingsProvidi…
authored
273
274 If `YES`, undocumented members are still used for output generation. If `NO`, these members are ignored, as if they are not part of the object. Note that this only affects documented objects: if an object is not documented and none of it's members is documented, the object is not processed for output, even if this value is `YES`!
275
276 @warning *Note:* This property works together with `keepUndocumentedObjects` and `findUndocumentedMembersDocumentation`. To understand how they are used, read documentation for `keepUndocumentedObjects`.
277
278 @see keepUndocumentedObjects
279 @see findUndocumentedMembersDocumentation
280 @see warnOnUndocumentedMember
281 */
282 @property (assign) BOOL keepUndocumentedMembers;
283
284 /** Specifies whether undocumented inherited methods or properties should be searched for in known places.
285
286 If `YES`, any undocumented overriden method or property is searched for in known super classes and adopted protocols and if documentation is found there, it is copied over. This works great for objects which would otherwise only show class documentation and no member. It's also how Apple documentation uses. Defaults to `YES`.
287
288 @warning *Note:* This property works together with `keepUndocumentedObjects` and `keepUndocumentedMembers`. To understand how they are used, read documentation for `keepUndocumentedObjects`.
289
290 @see keepUndocumentedObjects
291 @see keepUndocumentedMembers
292 */
293 @property (assign) BOOL findUndocumentedMembersDocumentation;
294
295 /** Indicates whether categories should be merges to classes they extend or not.
296
297 If `YES`, all methods from categories and extensions are merged to their classes. If `NO`, categories are left as independent objects in generated output. This is the main categories merging on/off switch, it merely enables or disables merging, other category merging settings define how exactly the methods from categories and extensions are merged into their classes.
298
299 Default value is `YES` and should be left so as this seems to be the way Apple has it's documentation generated.
300
301 @warning *Important:* Only categories for known project classes are merged. Categories to other framework classes, such as Foundation, AppKit or UIKit are not merged. In other words: only if the class source code is available on any of the given input paths, and is properly documented, it gets it's categories and extension methods merged! Also note that this option affects your documentation links - if any link is pointing to category that's going to be merged, it will be considered invalid link, so it's best to decide whther to merge categories of nor in advance and then consistently use properly formatted links.
302
303 @see keepMergedCategoriesSections
304 @see prefixMergedCategoriesSectionsWithCategoryName
305 */
306 @property (assign) BOOL mergeCategoriesToClasses;
307
0acde9d @tomaz When merging categories to classes, their comment is also merged. Add…
authored
308 /** Indicates wheter category comment should be merged to the end of the class comment or not.
309
310 This is only applicable if `mergeCategoriesToClasses` is `YES`.
311
312 @see mergeCategoriesToClasses
313 */
314 @property (assign) BOOL mergeCategoryCommentToClass;
315
1586e38 @tomaz Refactored settings handling by removing GBApplicationSettingsProvidi…
authored
316 /** Indicates whether category or extension sections should be preserved when merging into extended class.
317
318 If `YES`, all the sections from category or extension documentation are preserved. In such case, `prefixMergedCategoriesSectionsWithCategoryName` may optionally be used to prefix section name with category name or not. If `NO`, category or extension sections are ignored and a single section with category name is created in the class.
319
320 Default value is `NO`. If you use many sections within the categories, you should probably leave this option unchanged as preserving all category sections might yield fragmented class documentation. Experiment a bit to see what works best for you.
321
322 @warning *Note:* This option is ignored unless `mergeCategoriesToClasses` is used.
323
324 @see prefixMergedCategoriesSectionsWithCategoryName
325 @see mergeCategoriesToClasses
326 */
327 @property (assign) BOOL keepMergedCategoriesSections;
328
329 /** Indicates whether merged section names from categories should be prefixed with category name.
330
331 If `YES`, all merged section names from categories are prefixed with category name to make them more easily identifiable. If `NO`, section names are not changed. The first option is useful in case end users of your code are aware of different categories (if you're writting a framework for example). On the other hand, if you're using categories mostly as a way to split class definition to multiple files, you might want to keep this option off.
332
333 @warning *Note:* This option is ignored unless `mergeCategoriesToClasses` and `keepMergedCategoriesSections` is used. The option is also ignored for extensions; only section names are used for extensions!
334
335 @see keepMergedCategoriesSections
336 @see mergeCategoriesToClasses
337 */
338 @property (assign) BOOL prefixMergedCategoriesSectionsWithCategoryName;
339
e6c5e51 @tomaz Refactored GBMethodData to include prefixed selector builtin and adde…
authored
340 /** Indicates whteher local methods and properties cross references texts should be prefixed when used in related items list.
341
342 If `YES`, instance methods are prefixed with `-`, class methods with `+` and properties with `@property` when used as cross reference in related items list (i.e. see also section for methods). If `NO`, no prefix is used.
343 */
344 @property (assign) BOOL prefixLocalMembersInRelatedItemsList;
345
32ff996 @tomaz Addressing `&` and `&token;` issues when indexing documentation set, …
authored
346 /** Specifies whether we should treat docsetutil indexing errors as fatals or not.
347
348 Turning this to `YES` will cause docsetutil indexing error failing build, otherwise it will continue with remaining files. The main reason for implementing this is to allow handling uncompatible descriptions as graceful as possible.
349 */
350 @property (assign) BOOL treatDocSetIndexingErrorsAsFatals;
351
352 /** Species the threshold below which exit codes are truncated to zero.
353
354 This affects the reported exit code when ending a run session. It allows users preventing reporting certain types of exit codes, based on the given threshold. If the reported exit code is lower than the given threshold, zero is returned instead. If the reported exit code is equal or greater than the threshold, it is returned as the result of the tool.
355
356 This is useful to prevent higher level tools invoking appledoc (Xcode for example) treating reported warnings as invalid run for example. By default, this value is zero, so no exit code is suppressed.
357
358 @warning *Note:* Generally appledoc uses higher exit codes for more severe issues, so the greater the threshold, the more "permissive" the exit code will be, regardless of what happens inside the tool. However, crashes are always reported with proper exit codes, regardless of threshold value! Also note that the threshold value relies on the implementation of the exit codes #define values!
359 */
360 @property (assign) int exitCodeThreshold;
361
1586e38 @tomaz Refactored settings handling by removing GBApplicationSettingsProvidi…
authored
362 ///---------------------------------------------------------------------------------------
363 /// @name Warnings handling
364 ///---------------------------------------------------------------------------------------
365
b427cd7 @tomaz Implemented settings for enabling or disabling validation warnings.
authored
366 /** Indicates whether appledoc will warn if `--output` argument is not given.
367
368 Although appledoc still generates output in current directory, it's better to warn the user as in most cases this is not what she wants (for example if appledoc is invoked from Xcode build script, current working directory might point to some unpredicted location). appledoc also writes the exact path that will be used for generating output.
369
370 Note that in case documentation set is installed to Xcode, setting output path is irrelevant as all files from output are moved to locations Xcode uses for finding documentation sets.
371 */
372 @property (assign) BOOL warnOnMissingOutputPathArgument;
373
374 /** Indicates whether appledoc will warn if `--company-id` argument is not given.
375
376 Although appledoc deducts this information from other values, it's better to warn the user as deducted information doesn't necessarily produce correct results.
377
378 Note that the warning is only issued if documentation set creation is requested.
379 */
380 @property (assign) BOOL warnOnMissingCompanyIdentifier;
381
1586e38 @tomaz Refactored settings handling by removing GBApplicationSettingsProvidi…
authored
382 /** Indicates whether appledoc will warn if it encounters an undocumented class, category or protocol.
383
384 @see warnOnUndocumentedMember
385 */
386 @property (assign) BOOL warnOnUndocumentedObject;
387
4f44437 @tomaz Added settings for enabling or disabling various processing warnings.
authored
388 /** Indicates whether appledoc will warn if it encounters an undocumented method or property.
1586e38 @tomaz Refactored settings handling by removing GBApplicationSettingsProvidi…
authored
389
390 @see warnOnUndocumentedObject
391 */
392 @property (assign) BOOL warnOnUndocumentedMember;
393
4f44437 @tomaz Added settings for enabling or disabling various processing warnings.
authored
394 /** Indicates whether appledoc will warn if it encounters an empty description (@bug, @warning, example section etc.).
395 */
396 @property (assign) BOOL warnOnEmptyDescription;
397
398 /** Indicates whether appledoc will warn if it encounters unknown directive or styling element.
399 */
400 @property (assign) BOOL warnOnUnknownDirective;
401
7aa04af @tomaz Implemented optional disabling of invalid cross reference warnings.
authored
402 /** Indicates whether invalid cross reference should result in warning or not. */
403 @property (assign) BOOL warnOnInvalidCrossReference;
404
3a8da42 @tomaz Implemented optional disabling for missing method arguments warnings.
authored
405 /** Indicates whether missing method argument descriptions in comments should result in warnings or not. */
406 @property (assign) BOOL warnOnMissingMethodArgument;
407
1586e38 @tomaz Refactored settings handling by removing GBApplicationSettingsProvidi…
authored
408 ///---------------------------------------------------------------------------------------
409 /// @name Application-wide HTML helpers
410 ///---------------------------------------------------------------------------------------
411
604dffb @tomaz Fixed code blocks auto generated links handling.
authored
412 /** Specifies whether cross references should be embedded to special strings when processing Markdown.
413
414 This should be left to default value, however it's useful to prevent embedding for unit testing.
415
416 @see stringByEmbeddingCrossReference:
a85a42b @tomaz Fixed conversion of single to double star within example blocks and s…
authored
417 @see embedAppledocBoldMarkersWhenProcessingMarkdown
604dffb @tomaz Fixed code blocks auto generated links handling.
authored
418 */
419 @property (assign) BOOL embedCrossReferencesWhenProcessingMarkdown;
420
a85a42b @tomaz Fixed conversion of single to double star within example blocks and s…
authored
421 /** Specifies whether cross references should be embedded to special strings when processing Markdown.
422
423 This should be left to default value, however it's useful to prevent embedding for unit testing.
424
425 @see stringByEmbeddingCrossReference:
426 @see embedCrossReferencesWhenProcessingMarkdown
427 */
428 @property (assign) BOOL embedAppledocBoldMarkersWhenProcessingMarkdown;
429
430 /** Returns a new string with the given Markdown reference embedded in special cross reference markers used for post processing.
604dffb @tomaz Fixed code blocks auto generated links handling.
authored
431
432 This should be used for all generated cross references, so that we can later detect them when converting HTML with `stringByConvertingMarkdownToHTML:`.
433
434 @warning *Important:* Behavior of this method depends on `embedCrossReferencesWhenProcessingMarkdown` value. If it's `YES`, strings are embedded, otherwise the given value is returned without enmbedding.
435
436 @param value The string to embedd.
437 @return Returns embedded string.
438 @see stringByConvertingMarkdownToHTML:
439 @see embedCrossReferencesWhenProcessingMarkdown
440 */
441 - (NSString *)stringByEmbeddingCrossReference:(NSString *)value;
442
a85a42b @tomaz Fixed conversion of single to double star within example blocks and s…
authored
443 /** Returns a new string with the given value embedded in special bold markers used for post processing.
444
445 This should be used for all appledoc style bold markers (single star), so that we can later detect them when converting HTML with `stringByConvertingMarkdownToHTML:`.
446
447 @warning *Important:* Behavior of this method depends on `embedAppledocBoldMarkersWhenProcessingMarkdown` value. If it's `YES`, strings are embedded, otherwise value is returned without embedding.
448
449 @param value The string to embedd.
450 @return Returns embedded string.
451 @see stringByConvertingMarkdownToHTML:
452 @see embedAppledocBoldMarkersWhenProcessingMarkdown
453 */
454 - (NSString *)stringByEmbeddingAppledocBoldMarkers:(NSString *)value;
455
593ea57 @tomaz Refactored HTML templates to use new layout.
authored
456 /** Returns a new string containing HTML representation of the given Markdown string.
457
604dffb @tomaz Fixed code blocks auto generated links handling.
authored
458 This is the main method for converting Markdown to HTML. It works in two phases: first the Markdown engine is asked to convert the given string to HTML, then the string is cleaned up so that it contains proper HTML code. Cleaning up phase consists of:
459
460 - Cleaning any appledoc generated cross reference inside `<pre>` blocks. Markdown doesn't process links here, so in case appledoc detects known object and converts it to Markdown style link, the Markdown syntaxt is left untouched. This phase makes sure all such occurences are cleaned up to original text. This is only invoked if `embedCrossReferencesWhenProcessingMarkdown` value is `YES`!
593ea57 @tomaz Refactored HTML templates to use new layout.
authored
461
462 @param markdown Markdown source string to convert.
463 @return Returns converted string.
604dffb @tomaz Fixed code blocks auto generated links handling.
authored
464 @see stringByEmbeddingCrossReference:
ac26896 @tomaz Fixed docsetutil `Entity '' not defined` error.
authored
465 @see stringByConvertingMarkdownToText:
593ea57 @tomaz Refactored HTML templates to use new layout.
authored
466 @see stringByEscapingHTML:
467 */
ac26896 @tomaz Fixed docsetutil `Entity '' not defined` error.
authored
468 - (NSString *)stringByConvertingMarkdownToHTML:(NSString *)markdown;
469
470 /** Returns a new string containing text representation of the given Markdown string.
471
472 The main responsibility of this method is to strip Markdown links to names only to give text more readability when used in Xcode quick help. Although the name suggests this can handle Markdown strings, it's intended to be given appledoc comment string, prior to passing it to `GBCommentsProcessor`.
473
474 @param markdown Markdown source string to convert.
475 @return Returns converted string.
476 @see stringByConvertingMarkdownToHTML:
477 @see stringByEscapingHTML:
478 */
479 - (NSString *)stringByConvertingMarkdownToText:(NSString *)markdown;
593ea57 @tomaz Refactored HTML templates to use new layout.
authored
480
d7ece46 @tomaz Fixed HTML and XML handling within example blocks. Closes #54.
authored
481 /** Returns a new string by escaping the given HTML.
482
483 @param string HTML string to escape.
484 @return Returns escaped HTML string.
ac26896 @tomaz Fixed docsetutil `Entity '' not defined` error.
authored
485 @see stringByConvertingMarkdownToHTML:
486 @see stringByConvertingMarkdownToText:
d7ece46 @tomaz Fixed HTML and XML handling within example blocks. Closes #54.
authored
487 */
488 - (NSString *)stringByEscapingHTML:(NSString *)string;
489
1586e38 @tomaz Refactored settings handling by removing GBApplicationSettingsProvidi…
authored
490 /** Returns HTML reference name for the given object.
491
97db241 @tomaz Implemented possibility to add arbitrary documentation. Closes #7.
authored
492 This should only be used for creating anchors that need to be referenced from other parts of the same HTML file. The method works for static documents, top-level objects as well as their members.
1586e38 @tomaz Refactored settings handling by removing GBApplicationSettingsProvidi…
authored
493
494 @param object The object for which to return reference name.
495 @return Returns the reference name of the object.
496 @exception NSException Thrown if the given object is `nil`.
497 @see htmlReferenceForObject:fromSource:
498 @see htmlReferenceForObjectFromIndex:
499 */
500 - (NSString *)htmlReferenceNameForObject:(GBModelBase *)object;
501
502 /** Returns relative HTML reference to the given object from the context of the given source object.
503
504 This is useful for generating hrefs from one object HTML file to another. This is the swiss army knife king of a method for all hrefs generation. It works for any kind of links:
505
506 - Index to top-level object (if source is `nil`).
507 - Index to a member of a top-level object (if source is `nil`).
508 - Top-level object to same top-level object.
509 - Top-level object to a different top-level object.
510 - Top-level object to one of it's members.
511 - Member object to it's top-level object.
512 - Member object to another top-level object.
513 - Member object to another member of the same top-level object.
514 - Member object to a member of another top-level object.
515
516 @param object The object for which to generate the reference to.
517 @param source The source object from which to generate the reference from or `nil` for index to object reference.
518 @return Returns the reference string.
519 @exception NSException Thrown if object is `nil`.
520 @see htmlReferenceForObjectFromIndex:
521 @see htmlReferenceNameForObject:
522 */
523 - (NSString *)htmlReferenceForObject:(GBModelBase *)object fromSource:(GBModelBase *)source;
524
525 /** Returns relative HTML reference to the given object from the context of index file.
526
527 This is simply a helper method for `htmlReferenceForObject:fromSource:`, passing the given object as object parameter and `nil` as source.
528
d6b842b @tomaz Fixed comment warnings for various objects.
authored
529 @param object The object for which to generate the reference to.
1586e38 @tomaz Refactored settings handling by removing GBApplicationSettingsProvidi…
authored
530 @return Returns the reference string.
531 @exception NSException Thrown if object is `nil`.
97db241 @tomaz Implemented possibility to add arbitrary documentation. Closes #7.
authored
532 @see htmlRelativePathToIndexFromObject:
1586e38 @tomaz Refactored settings handling by removing GBApplicationSettingsProvidi…
authored
533 @see htmlReferenceForObject:fromSource:
534 @see htmlReferenceNameForObject:
535 */
536 - (NSString *)htmlReferenceForObjectFromIndex:(GBModelBase *)object;
537
97db241 @tomaz Implemented possibility to add arbitrary documentation. Closes #7.
authored
538 /** Returns relative HTML path from the given object to the index file location.
539
540 This is kind of reverse to `htmlReferenceForObjectFromIndex:`, except that it only returns the relative path, without index.html.
541
542 @param object The object from which to generate the path.
543 @return Returns relative path.
544 @exception NSException Thrown if object is `nil`.
545 @see htmlReferenceForObjectFromIndex:
546 @see htmlReferenceForObject:fromSource:
547 @see htmlReferenceNameForObject:
548 */
549 - (NSString *)htmlRelativePathToIndexFromObject:(id)object;
550
551 /** The subpath within `outputPath` where static documents are stored.
552 */
553 @property (readonly) NSString *htmlStaticDocumentsSubpath;
554
1586e38 @tomaz Refactored settings handling by removing GBApplicationSettingsProvidi…
authored
555 /** The file extension for html files.
556 */
557 @property (readonly) NSString *htmlExtension;
558
559 ///---------------------------------------------------------------------------------------
97db241 @tomaz Implemented possibility to add arbitrary documentation. Closes #7.
authored
560 /// @name Application-wide template files helpers
561 ///---------------------------------------------------------------------------------------
562
563 /** Determines if the given path represents a template file or not.
564
565 The method simply checks the if the name of the last path component ends with `-template` string.
566
567 @param path The path to check.
568 @return Returns `YES` if the given path represents a template file, `NO` otherwise.
569 @see outputFilenameForTemplatePath:
570 */
571 - (BOOL)isPathRepresentingTemplateFile:(NSString *)path;
572
573 /** Returns the actual filename of the output file from the given template path.
574
575 The method simply removes `-template` string from the file name and returns the resulting string. The result is the filename without path but with the same extension as the original path. If the given path doesn't represent a template file, the result is equivalent to sending `lastPathComponent` to the input path.
576
577 @param path The path to convert.
578 @return Returns filename that can be used for output.
e2c8832 @tomaz Fixed warnings due to invalid cross references in various comments.
authored
579 @see isPathRepresentingTemplateFile:
97db241 @tomaz Implemented possibility to add arbitrary documentation. Closes #7.
authored
580 @see templateFilenameForOutputPath:
581 */
582 - (NSString *)outputFilenameForTemplatePath:(NSString *)path;
583
584 /** Returns the template name for the given filename.
585
586 This is reverse method for `outputFilenameForTemplatePath`. It adds `-template` string to the end of the given path filename, before the optional extension.
587
588 @param path The path to convert.
589 @return Returns template filename.
e2c8832 @tomaz Fixed warnings due to invalid cross references in various comments.
authored
590 @see isPathRepresentingTemplateFile:
97db241 @tomaz Implemented possibility to add arbitrary documentation. Closes #7.
authored
591 @see outputFilenameForTemplatePath:
592 */
593 - (NSString *)templateFilenameForOutputPath:(NSString *)path;
594
595 ///---------------------------------------------------------------------------------------
1586e38 @tomaz Refactored settings handling by removing GBApplicationSettingsProvidi…
authored
596 /// @name Helper methods
597 ///---------------------------------------------------------------------------------------
598
599 /** Replaces all occurences of placeholder strings in all related values of the receiver.
600
601 This message should be sent once all the values have been set. It is a convenience method that prepares all values that can use placeholder strings. From this point on, the rest of the application can simply use properties to get final values instead of sending `stringByReplacingOccurencesOfPlaceholdersInString:` all the time.
602
603 Note that `stringByReplacingOccurencesOfPlaceholdersInString:` is still available for cases where placeholder strings may be used elsewhere (template files for example).
604
605 @see stringByReplacingOccurencesOfPlaceholdersInString:
606 */
607 - (void)replaceAllOccurencesOfPlaceholderStringsInSettingsValues;
608
609 /** Replaces all placeholders occurences in the given string.
610
611 This method provides application-wide string placeholders replacement functionality. It replaces all known placeholders with actual values from the receiver. Placeholders are identified by a dollar mark, followed by placeholder name. The following placeholders are supported (note that case is important!):
612
f18465e @tomaz Fixed HTML footer year and last update strings. Closes #49.
authored
613 - `%PROJECT`: Replaced by `projectName` value.
614 - `%PROJECTID`: Replaced by `projectIdentifier` value.
615 - `%COMPANY`: Replaced by `projectCompany` value.
616 - `%COMPANYID`: Replaced by `companyIdentifier` value.
617 - `%VERSION`: Replaced by `projectVersion` value.
618 - `%VERSIONID`: Replaced by `versionIdentifier` value.
619 - `%DOCSETBUNDLEFILENAME`: Replaced by `docsetBundleFilename` value.
620 - `%DOCSETATOMFILENAME`: Replaced by `docsetAtomFilename` value.
621 - `%DOCSETPACKAGEFILENAME`: Replaced by `docsetPackageFilename` value.
622 - `%YEAR`: Replaced by current year as four digit string.
623 - `%UPDATEDATE`: Replaced by current date in the form of year, month and day with format `YYYY-MM-DD`. For example `2010-11-30`.
1586e38 @tomaz Refactored settings handling by removing GBApplicationSettingsProvidi…
authored
624
625 @param string The string to replace placeholder occurences in.
626 @return Returns new string with all placeholder occurences replaced.
627 @see replaceAllOccurencesOfPlaceholderStringsInSettingsValues
628 */
629 - (NSString *)stringByReplacingOccurencesOfPlaceholdersInString:(NSString *)string;
630
631 ///---------------------------------------------------------------------------------------
632 /// @name Helper classes
633 ///---------------------------------------------------------------------------------------
634
635 /** Returns the `GBCommentComponentsProvider` object that identifies comment components. */
636 @property (retain) GBCommentComponentsProvider *commentComponents;
637
638 /** Returns the `GBApplicationStringsProvider` object that specifies all string templates used for output generation. */
639 @property (retain) GBApplicationStringsProvider *stringTemplates;
640
7d6a323 @tomaz Copied all the changes from the old generating branch.
authored
641 @end
1f23b3e @tomaz Refactored template placeholder strings by moving them to global cons…
authored
642
643 #pragma -
644
645 extern NSString *kGBTemplatePlaceholderCompanyID;
646 extern NSString *kGBTemplatePlaceholderProjectID;
647 extern NSString *kGBTemplatePlaceholderVersionID;
648 extern NSString *kGBTemplatePlaceholderProject;
649 extern NSString *kGBTemplatePlaceholderCompany;
650 extern NSString *kGBTemplatePlaceholderVersion;
651 extern NSString *kGBTemplatePlaceholderDocSetBundleFilename;
652 extern NSString *kGBTemplatePlaceholderDocSetAtomFilename;
653 extern NSString *kGBTemplatePlaceholderDocSetPackageFilename;
654 extern NSString *kGBTemplatePlaceholderYear;
655 extern NSString *kGBTemplatePlaceholderUpdateDate;
Something went wrong with that request. Please try again.