-
Notifications
You must be signed in to change notification settings - Fork 2
/
DocPage.h
142 lines (114 loc) · 5.23 KB
/
DocPage.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
/**
<abstract>DocPage represents a documentation page.</abstract>
Copyright (C) 2008 Nicolas Roard
Author: Nicolas Roard
Author: Quentin Mathe <[email protected]>
Date: June 2008
License: Modified BSD (see COPYING)
*/
#import <Foundation/Foundation.h>
#import <EtoileFoundation/EtoileFoundation.h>
@class DocHeader, DocMethod, DocFunction, DocMacro, DocConstant, DocCDataType, DocHTMLElement, DocIVar, DocProperty;
/** @group Page Generation
A documentation page that weaves various HTML, GSDoc, Markdown, plist, and ObjC
files (usually provided on the command-line), into a new HTML representation
based on the template tags embedded in the HTML or Markdown content.
You usually don't instantiate this class, but give the documentation input files
to DocPageWeaver which will create new DocPage instances and return
them.<br />
The returned pages can then be written to disk with -writeToURL: or
their HTML representation retrieved with -HTMLString.
Subclasses can be written to customize the presentation and how the various
elements (methods, macros, menu etc.) are laid out. Subclassing support is
experimental and untested. */
@interface DocPage : NSObject
{
@private
/* Source & Template */
NSString *documentType;
NSString *documentPath;
NSString *documentContent;
NSString *templateContent;
NSString *menuContent;
NSString *weavedContent;
/* Doc Element Tree
Each doc element dictionaries is organized as described:
{ taskOrGroupName = ( doc element 1, doc element 2 ...); ... } */
DocHeader *header;
@protected
NSMutableArray *subheaders;
NSMutableArray *methods;
NSMutableArray *functions;
NSMutableArray *constants;
NSMutableArray *macros;
NSMutableArray *otherDataTypes;
NSMutableArray *ivars;
NSMutableArray *properties;
}
/** @taskunit Initialization and Identity */
/** Initialises and returns a new documentation page that combines the given
input files. */
- (id) initWithDocumentFile: (NSString *)aDocumentPath
templateFile: (NSString *)aTemplatePath
menuFile: (NSString *)aMenuPath;
/** Returns the page name.
Can be used as a file name when saving the page, as <em>etdocgen</em> does. */
- (NSString *) name;
/** @taskunit Writing to File */
/** Writes the page to the given URL atomically. */
- (void) writeToURL: (NSURL *)outputURL;
/** @taskunit Page Building */
/** Sets the page header. */
- (void) setHeader: (DocHeader *)aHeader;
/** Returns the page header. */
- (DocHeader *) header;
/** Adds a subheader to the page.
Subheaders are expected to be positioned under the main header.<br />
A subheader can be used to regroup related documentation tree elements. */
- (void) addSubheader: (DocHeader *)aHeader;
/** Adds a method documentation to the page. */
- (void) addMethod: (DocMethod *)aMethod;
/** Adds a function documentation to the page. */
- (void) addFunction: (DocFunction *)aFunction;
/** Adds a constant documentation to the page. */
- (void) addConstant: (DocConstant *)aConstant;
/** Adds a macro documentation to the page. */
- (void) addMacro: (DocMacro *)aMacro;
/** Adds another data type documentation to the page. */
- (void) addOtherDataType: (DocCDataType *)anotherDataType;
/** Adds an ivar documentation to the page. */
- (void) addIVar: (DocIVar *)anIVar;
/** Adds a property documentation to the page. */
- (void) addProperty: (DocProperty *)aProperty;
/** @taskunit HTML Generation */
/** Returns a string representation of the whole page by weaving the input files. */
- (NSString *) HTMLString;
/** Returns the main page content rendered as an DocHTMLElement array, including
elements such as <em>Instance Methods</em>,<em>Macros</em> etc.
Menu, navigation bar etc. are not present in the returned HTML representation
unlike -HTMLString which does include them in its ouput. */
- (NSArray *) mainContentHTMLRepresentations;
/** <override-dummy />
Returns the HTML element tree into which the main header should be rendered.
By default, returns the -[DocHeader HTMLRepresentation].
Can be overriden to return a custom representation. */
- (DocHTMLElement *) HTMLRepresentationForHeader: (DocHeader *)aHeader;
- (DocHTMLElement *) HTMLOverviewRepresentationForGroupNamed: (NSString *)aGroup;
/** Returns the given doc elements rendered as a HTML element tree.
The array argument must contain ETKeyValuePair and not DocElement objects.<br />
For -[ETKeyValuePair value], every pairs must return a mutable array that
contains DocElement objects only.
Doc elements are sorted by their -[ETKeyValuePair key] such as task or group
name, before being rendered to HTML.
Group or task names are output with a <h4> header (<h3> when the title is nil).<br />
A title is also added, which uses a <h3> header.
repSelector should usually be -HTMLRepresentation. Additional representations
can be added to the DocElement subclasses such as
-[DocHeader HTMLTOCRepresentation]. You can pass such a selector in argument to
use a custom representation in the output.
See also DocElement. */
- (DocHTMLElement *) HTMLRepresentationWithTitle: (NSString *)aTitle
elements: (NSArray *)elementsByGroup
HTMLRepresentationSelector: (SEL)repSelector
groupSeparator: (DocHTMLElement *)aSeparator;
@end