Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 99 lines (70 sloc) 4.821 kb
e12fb72 @tomaz Implemented basic infrastructure for comment derived values handling.
authored
1 //
2 // GBCommentComponent.h
3 // appledoc
4 //
5 // Created by Tomaz Kragelj on 14.2.11.
6 // Copyright 2011 Gentle Bytes. All rights reserved.
7 //
8
9 #import <Foundation/Foundation.h>
10
11 @class GBSourceInfo;
12
13 /** Handles individual `GBComment` component.
14
15 A comment component is basic building block for `GBComment`s. It's primary responsibility is storing representation suitable for Markdown processor. The reason for splitting comment text into components is to allow support for various output styles, such as `@warning` and `@bug`. These require slightly different preprocessing. This object is lightweight, it doesn't do any processing, just provides properties that hold the data, it's the job of higher level components to setup the data properly.
0d41271 @tomaz Implemented settings property for GBCommentComponents and it's assignmen...
authored
16
17 @warning *Important:* In order to get proper value of `htmlValue`, `GBApplicationSettingsProvider` instance must be assigned to `settings` before using `htmlValue`! This is handled during processing phase automatically at the time of creation of the component, so it works seamlesly. It's good to be aware of this fact though as it may lead to surprises later on.
e12fb72 @tomaz Implemented basic infrastructure for comment derived values handling.
authored
18 */
19 @interface GBCommentComponent : NSObject {
20 @private
21 NSString *_htmlValue;
ac26896 @tomaz Fixed docsetutil `Entity '' not defined` error.
authored
22 NSString *_textValue;
e12fb72 @tomaz Implemented basic infrastructure for comment derived values handling.
authored
23 }
24
25 ///---------------------------------------------------------------------------------------
26 /// @name Initialization & disposal
27 ///---------------------------------------------------------------------------------------
28
29 /** Returns a new autoreleased instance of the comment with the given string value.
30
31 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.
32
33 @param value String value to set.
34 @return Returns initialized object or `nil` if initialization fails.
e2c8832 @tomaz Fixed warnings due to invalid cross references in various comments.
authored
35 @see componentWithStringValue:sourceInfo:
e12fb72 @tomaz Implemented basic infrastructure for comment derived values handling.
authored
36 */
37 + (id)componentWithStringValue:(NSString *)value;
38
39 /** Returns a new autoreleased instance of the comment with the given string value and source info.
40
41 This is a helper initializer which allows setting default values with a single message.
42
43 @param value String value to set.
44 @param info Source info to set.
45 @return Returns initialized object or `nil` if initialization fails.
e2c8832 @tomaz Fixed warnings due to invalid cross references in various comments.
authored
46 @see componentWithStringValue:
e12fb72 @tomaz Implemented basic infrastructure for comment derived values handling.
authored
47 */
48 + (id)componentWithStringValue:(NSString *)value sourceInfo:(GBSourceInfo *)info;
49
50 ///---------------------------------------------------------------------------------------
51 /// @name Component data
52 ///---------------------------------------------------------------------------------------
53
54 /** Component's string value from the source code.
55 */
56 @property (copy) NSString *stringValue;
57
58 /** Component's markdown value, derived from `stringValue`.
59 */
60 @property (copy) NSString *markdownValue;
61
62 /** Component's HTML value, derived by passing assigned `markdownValue` through Markdown processor.
63
ac26896 @tomaz Fixed docsetutil `Entity '' not defined` error.
authored
64 This value is derived when first used, the value is cached afterwards and cached value is returned from subsequent calls. Internally [GBApplicationSettingsProvider stringByConvertingMarkdownToHTML:] is used for conversion.
0d41271 @tomaz Implemented settings property for GBCommentComponents and it's assignmen...
authored
65
66 @warning *Important:* This value requires `settings` to be assigned! If settings are not assigned, the value or `markdownValue` is returned but is not cached, so that any subsequent assigning of settings would pick up proper html.
ac26896 @tomaz Fixed docsetutil `Entity '' not defined` error.
authored
67
68 @see textValue
e12fb72 @tomaz Implemented basic infrastructure for comment derived values handling.
authored
69 */
70 @property (readonly) NSString *htmlValue;
71
ae61b04 @tomaz Implemented some basic cleaning up when converting from Markdown to text...
authored
72 /** Component's text value, derived by passing assigned `markdownValue` through text processor.
ac26896 @tomaz Fixed docsetutil `Entity '' not defined` error.
authored
73
74 The result is suitable for using in documentation set tokens file. Using converted HTML may result in errors when indexing due to usage of escaped HTML symbols (for example any `&ndash;` would result in docsetutil error `Entity 'ndash' not defined`. This value is derived when first used, the value is cached afterwards and cached value is returned from subsequent calls. Internally [GBApplicationSettingsProvider stringByConvertingMarkdownToText:] is used for conversion.
75
ae61b04 @tomaz Implemented some basic cleaning up when converting from Markdown to text...
authored
76 @warning *Important:* This value requires `settings` to be assigned! If settings are not assigned, the value of `markdownValue` is returned but is not cached, so that any subsequent assigning of settings would pick up proper text.
ac26896 @tomaz Fixed docsetutil `Entity '' not defined` error.
authored
77
78 @see htmlValue
79 */
80 @property (readonly) NSString *textValue;
81
e12fb72 @tomaz Implemented basic infrastructure for comment derived values handling.
authored
82 /** Source file information.
83 */
63ba09d @sptramer [ISSUE-439] First pass on converting appledoc from GC->ARC.
sptramer authored
84 @property (strong) GBSourceInfo *sourceInfo;
e12fb72 @tomaz Implemented basic infrastructure for comment derived values handling.
authored
85
0d41271 @tomaz Implemented settings property for GBCommentComponents and it's assignmen...
authored
86 ///---------------------------------------------------------------------------------------
87 /// @name Helper attributes
88 ///---------------------------------------------------------------------------------------
89
ac26896 @tomaz Fixed docsetutil `Entity '' not defined` error.
authored
90 /** This is used only for related items to allow creating documentation set identifiers.
91 */
63ba09d @sptramer [ISSUE-439] First pass on converting appledoc from GC->ARC.
sptramer authored
92 @property (strong) id relatedItem;
ac26896 @tomaz Fixed docsetutil `Entity '' not defined` error.
authored
93
0d41271 @tomaz Implemented settings property for GBCommentComponents and it's assignmen...
authored
94 /** Settings used for creating various values.
95 */
63ba09d @sptramer [ISSUE-439] First pass on converting appledoc from GC->ARC.
sptramer authored
96 @property (strong) id settings;
0d41271 @tomaz Implemented settings property for GBCommentComponents and it's assignmen...
authored
97
e12fb72 @tomaz Implemented basic infrastructure for comment derived values handling.
authored
98 @end
Something went wrong with that request. Please try again.