Root/
Source at commit 1322 created 12 years 8 months ago. By meklort, Add doxygen to utils folder | |
---|---|
1 | /******************************************************************************␊ |
2 | *␊ |
3 | * $Id: outputgen.h,v 1.48 2001/03/19 19:27:41 root Exp $␊ |
4 | *␊ |
5 | * Copyright (C) 1997-2011 by Dimitri van Heesch.␊ |
6 | *␊ |
7 | * Permission to use, copy, modify, and distribute this software and its␊ |
8 | * documentation under the terms of the GNU General Public License is hereby ␊ |
9 | * granted. No representations are made about the suitability of this software ␊ |
10 | * for any purpose. It is provided "as is" without express or implied warranty.␊ |
11 | * See the GNU General Public License for more details.␊ |
12 | *␊ |
13 | * Documents produced by Doxygen are derivative works derived from the␊ |
14 | * input used in their production; they are not affected by this license.␊ |
15 | *␊ |
16 | */␊ |
17 | ␊ |
18 | #ifndef OUTPUTGEN_H␊ |
19 | #define OUTPUTGEN_H␊ |
20 | ␊ |
21 | #include "qtbc.h"␊ |
22 | #include "ftextstream.h"␊ |
23 | #include <qbuffer.h>␊ |
24 | #include <qfile.h>␊ |
25 | #include <qstack.h>␊ |
26 | #include "index.h"␊ |
27 | #include "section.h"␊ |
28 | ␊ |
29 | class ClassDiagram;␊ |
30 | class DotClassGraph;␊ |
31 | class DotInclDepGraph;␊ |
32 | class DotCallGraph;␊ |
33 | class DotDirDeps;␊ |
34 | class DotGfxHierarchyTable;␊ |
35 | class DotGroupCollaboration;␊ |
36 | class DocNode;␊ |
37 | class MemberDef;␊ |
38 | class GroupDef;␊ |
39 | class Definition;␊ |
40 | ␊ |
41 | /*! \brief Output interface for code parser. ␊ |
42 | */␊ |
43 | class CodeOutputInterface␊ |
44 | {␊ |
45 | public:␊ |
46 | virtual ~CodeOutputInterface() {}␊ |
47 | /*! Writes an ASCII string to the output. This function should keep ␊ |
48 | * spaces visible, should break lines at a newline and should convert ␊ |
49 | * tabs to the right number of spaces.␊ |
50 | */␊ |
51 | virtual void codify(const char *s) = 0;␊ |
52 | ␊ |
53 | /*! Writes a link to an object in a code fragment.␊ |
54 | * \param ref If this is non-zero, the object is to be found in␊ |
55 | * an external documentation file.␊ |
56 | * \param file The file in which the object is located.␊ |
57 | * \param anchor The anchor uniquely identifying the object within ␊ |
58 | * the file. ␊ |
59 | * \param name The text to display as a placeholder for the link.␊ |
60 | * \param tooltip The tooltip to display when the mouse is on the link.␊ |
61 | */␊ |
62 | virtual void writeCodeLink(const char *ref,const char *file,␊ |
63 | const char *anchor,const char *name,␊ |
64 | const char *tooltip) = 0;␊ |
65 | ␊ |
66 | virtual void writeLineNumber(const char *ref,const char *file,␊ |
67 | const char *anchor,int lineNumber) = 0;␊ |
68 | virtual void startCodeLine() = 0;␊ |
69 | virtual void endCodeLine() = 0;␊ |
70 | virtual void startCodeAnchor(const char *label) = 0;␊ |
71 | virtual void endCodeAnchor() = 0;␊ |
72 | virtual void startFontClass(const char *) = 0;␊ |
73 | virtual void endFontClass() = 0;␊ |
74 | virtual void writeCodeAnchor(const char *name) = 0;␊ |
75 | virtual void linkableSymbol(int line,const char *symName,␊ |
76 | Definition *symDef,Definition *context) = 0;␊ |
77 | };␊ |
78 | ␊ |
79 | /*! \brief Base Interface used for generating output outside of the␊ |
80 | * comment blocks.␊ |
81 | *␊ |
82 | * This abstract class is used by output generation functions␊ |
83 | * to generate the output for a specific format,␊ |
84 | * or a list of formats (see OutputList). This interface␊ |
85 | * contains functions that generate fragments of the output.␊ |
86 | */␊ |
87 | class BaseOutputDocInterface : public CodeOutputInterface␊ |
88 | {␊ |
89 | public:␊ |
90 | virtual ~BaseOutputDocInterface() {}␊ |
91 | enum ParamListTypes { Param, RetVal, Exception };␊ |
92 | enum SectionTypes { /*See, Return, Author, Version, ␊ |
93 | Since, Date, Bug, Note,␊ |
94 | Warning, Par, Deprecated, Pre, ␊ |
95 | Post, Invar, Remark, Attention, ␊ |
96 | Todo, Test, RCS, */ EnumValues, ␊ |
97 | Examples ␊ |
98 | };␊ |
99 | ␊ |
100 | virtual void parseDoc(const char *,int, const char *,MemberDef *,␊ |
101 | const QCString &,bool) {} ␊ |
102 | virtual void parseText(const QCString &) {}␊ |
103 | ␊ |
104 | /*! Start of a bullet list: e.g. \c \<ul\> in html. startItemListItem() is␊ |
105 | * Used for the bullet items.␊ |
106 | */␊ |
107 | virtual void startItemList() = 0;␊ |
108 | ␊ |
109 | /*! Writes a list item for a bullet or enumerated ␊ |
110 | * list: e.g. \c \<li\> in html ␊ |
111 | */␊ |
112 | virtual void startItemListItem() = 0;␊ |
113 | ␊ |
114 | /*! Writes a list item for a bullet or enumerated ␊ |
115 | * list: e.g. \c \</li\> in html ␊ |
116 | */␊ |
117 | virtual void endItemListItem() = 0;␊ |
118 | ␊ |
119 | /*! Ends a bullet list: e.g. \c \</ul\> in html */␊ |
120 | virtual void endItemList() = 0;␊ |
121 | ␊ |
122 | /*! Writes an ASCII string to the output. Converts characters that have␊ |
123 | * A special meaning, like \c & in html. ␊ |
124 | */␊ |
125 | virtual void docify(const char *s) = 0;␊ |
126 | ␊ |
127 | /*! Writes a single ASCII character to the output. Converts characters␊ |
128 | * that have a special meaning.␊ |
129 | */␊ |
130 | virtual void writeChar(char c) = 0;␊ |
131 | ␊ |
132 | /*! Writes an ASCII string to the output, \e without converting ␊ |
133 | * special characters. ␊ |
134 | */␊ |
135 | virtual void writeString(const char *text) = 0;␊ |
136 | ␊ |
137 | /*! Starts a new paragraph */␊ |
138 | //virtual void newParagraph() = 0;␊ |
139 | ␊ |
140 | /*! Starts a new paragraph */␊ |
141 | virtual void startParagraph() = 0;␊ |
142 | /*! Ends a paragraph */␊ |
143 | virtual void endParagraph() = 0;␊ |
144 | ␊ |
145 | /*! Writes a link to an object in the documentation.␊ |
146 | * \param ref If this is non-zero, the object is to be found in␊ |
147 | * an external documentation file.␊ |
148 | * \param file The file in which the object is located.␊ |
149 | * \param anchor The anchor uniquely identifying the object within ␊ |
150 | * the file. ␊ |
151 | * \param name The text to display as a placeholder for the link.␊ |
152 | */␊ |
153 | virtual void writeObjectLink(const char *ref,const char *file,␊ |
154 | const char *anchor, const char *name) = 0;␊ |
155 | ␊ |
156 | ␊ |
157 | /*! Starts a (link to an) URL found in the documentation.␊ |
158 | * \param url The URL to link to.␊ |
159 | */␊ |
160 | virtual void startHtmlLink(const char *url) = 0;␊ |
161 | ␊ |
162 | /*! Ends a link started by startHtmlLink().␊ |
163 | */␊ |
164 | virtual void endHtmlLink() = 0;␊ |
165 | ␊ |
166 | ␊ |
167 | /*! Changes the text font to bold face. The bold section ends with␊ |
168 | * endBold()␊ |
169 | */␊ |
170 | virtual void startBold() = 0;␊ |
171 | ␊ |
172 | /*! End a section of text displayed in bold face. */␊ |
173 | virtual void endBold() = 0;␊ |
174 | ␊ |
175 | /*! Changes the text font to fixed size. The section ends with␊ |
176 | * endTypewriter()␊ |
177 | */␊ |
178 | virtual void startTypewriter() = 0;␊ |
179 | ␊ |
180 | /*! End a section of text displayed in typewriter style. */␊ |
181 | virtual void endTypewriter() = 0;␊ |
182 | ␊ |
183 | /*! Changes the text font to italic. The italic section ends with␊ |
184 | * endEmphasis()␊ |
185 | */␊ |
186 | virtual void startEmphasis() = 0;␊ |
187 | ␊ |
188 | /*! Ends a section of text displayed in italic. */␊ |
189 | virtual void endEmphasis() = 0;␊ |
190 | ␊ |
191 | /*! Starts a source code fragment. The fragment will be␊ |
192 | * fed to the code parser (see code.h) for syntax highlighting␊ |
193 | * and cross-referencing. The fragment ends by a call to␊ |
194 | * endCodeFragment()␊ |
195 | */␊ |
196 | virtual void startCodeFragment() = 0;␊ |
197 | ␊ |
198 | /*! Ends a source code fragment␊ |
199 | */␊ |
200 | virtual void endCodeFragment() = 0;␊ |
201 | ␊ |
202 | ␊ |
203 | ␊ |
204 | ␊ |
205 | /*! Writes a horizontal ruler to the output */␊ |
206 | virtual void writeRuler() = 0;␊ |
207 | ␊ |
208 | /*! Starts a description list: e.g. \c \<dl\> in HTML ␊ |
209 | * Items are surrounded by startDescItem() and endDescItem()␊ |
210 | */␊ |
211 | virtual void startDescription() = 0;␊ |
212 | ␊ |
213 | /*! Ends a description list: e.g. \c \</dl\> in HTML */␊ |
214 | virtual void endDescription() = 0;␊ |
215 | ␊ |
216 | /*! Starts an item of a description list: e.g. \c \<dt\> in HTML. */␊ |
217 | virtual void startDescItem() = 0;␊ |
218 | ␊ |
219 | virtual void startDescForItem() = 0;␊ |
220 | virtual void endDescForItem() = 0;␊ |
221 | ␊ |
222 | /*! Ends an item of a description list and starts the ␊ |
223 | * description itself: e.g. \c \</dt\> in HTML. ␊ |
224 | */␊ |
225 | virtual void endDescItem() = 0;␊ |
226 | ␊ |
227 | virtual void startCenter() = 0;␊ |
228 | virtual void endCenter() = 0;␊ |
229 | virtual void startSmall() = 0;␊ |
230 | virtual void endSmall() = 0;␊ |
231 | ␊ |
232 | virtual void startSimpleSect(SectionTypes t,const char *file,␊ |
233 | const char *anchor,const char *title) = 0;␊ |
234 | virtual void endSimpleSect() = 0;␊ |
235 | virtual void startParamList(ParamListTypes t,const char *title) = 0;␊ |
236 | virtual void endParamList() = 0;␊ |
237 | ␊ |
238 | //virtual void writeDescItem() = 0;␊ |
239 | virtual void startTitle() = 0;␊ |
240 | virtual void endTitle() = 0;␊ |
241 | ␊ |
242 | virtual void writeAnchor(const char *fileName,const char *name) = 0;␊ |
243 | virtual void startSection(const char *,const char *,SectionInfo::SectionType) = 0;␊ |
244 | virtual void endSection(const char *,SectionInfo::SectionType) = 0;␊ |
245 | ␊ |
246 | virtual void lineBreak(const char *style) = 0;␊ |
247 | virtual void addIndexItem(const char *s1,const char *s2) = 0;␊ |
248 | ␊ |
249 | virtual void writeNonBreakableSpace(int) = 0;␊ |
250 | virtual void startDescTable() = 0;␊ |
251 | virtual void endDescTable() = 0;␊ |
252 | virtual void startDescTableTitle() = 0;␊ |
253 | virtual void endDescTableTitle() = 0;␊ |
254 | virtual void startDescTableData() = 0;␊ |
255 | virtual void endDescTableData() = 0;␊ |
256 | virtual void startTextLink(const char *file,const char *anchor) = 0;␊ |
257 | virtual void endTextLink() = 0;␊ |
258 | virtual void startPageRef() = 0;␊ |
259 | virtual void endPageRef(const char *,const char *) = 0;␊ |
260 | virtual void startSubsection() = 0;␊ |
261 | virtual void endSubsection() = 0;␊ |
262 | virtual void startSubsubsection() = 0;␊ |
263 | virtual void endSubsubsection() = 0;␊ |
264 | };␊ |
265 | ␊ |
266 | /*! \brief Abstract output generator.␊ |
267 | *␊ |
268 | * Subclass this class to add support for a new output format␊ |
269 | */␊ |
270 | class OutputGenerator : public BaseOutputDocInterface␊ |
271 | {␊ |
272 | public:␊ |
273 | enum OutputType { Html, Latex, Man, RTF, XML, DEF, Perl };␊ |
274 | ␊ |
275 | OutputGenerator();␊ |
276 | virtual ~OutputGenerator();␊ |
277 | ␊ |
278 | ///////////////////////////////////////////////////////////////␊ |
279 | // generic generator methods␊ |
280 | ///////////////////////////////////////////////////////////////␊ |
281 | virtual void enable() = 0;␊ |
282 | virtual void disable() = 0;␊ |
283 | virtual void enableIf(OutputType o) = 0;␊ |
284 | virtual void disableIf(OutputType o) = 0;␊ |
285 | virtual void disableIfNot(OutputType o) = 0;␊ |
286 | virtual bool isEnabled(OutputType o) = 0;␊ |
287 | virtual OutputGenerator *get(OutputType o) = 0;␊ |
288 | void startPlainFile(const char *name);␊ |
289 | void endPlainFile();␊ |
290 | //QCString getContents() const;␊ |
291 | bool isEnabled() const { return active; }␊ |
292 | void pushGeneratorState();␊ |
293 | void popGeneratorState();␊ |
294 | //void setEncoding(const QCString &enc) { encoding = enc; }␊ |
295 | //virtual void postProcess(QByteArray &) { }␊ |
296 | ␊ |
297 | virtual void printDoc(DocNode *,const char *langExt) = 0;␊ |
298 | ␊ |
299 | ///////////////////////////////////////////////////////////////␊ |
300 | // structural output interface␊ |
301 | ///////////////////////////////////////////////////////////////␊ |
302 | virtual void startFile(const char *name,const char *manName,␊ |
303 | const char *title) = 0;␊ |
304 | virtual void writeFooter() = 0;␊ |
305 | virtual void endFile() = 0;␊ |
306 | virtual void startIndexSection(IndexSections) = 0;␊ |
307 | virtual void endIndexSection(IndexSections) = 0;␊ |
308 | virtual void writePageLink(const char *,bool) = 0;␊ |
309 | virtual void startProjectNumber() = 0;␊ |
310 | virtual void endProjectNumber() = 0;␊ |
311 | virtual void writeStyleInfo(int part) = 0;␊ |
312 | virtual void startTitleHead(const char *) = 0;␊ |
313 | virtual void endTitleHead(const char *fileName,const char *name) = 0;␊ |
314 | virtual void startIndexListItem() = 0;␊ |
315 | virtual void endIndexListItem() = 0;␊ |
316 | virtual void startIndexList() = 0;␊ |
317 | virtual void endIndexList() = 0;␊ |
318 | virtual void startIndexKey() = 0;␊ |
319 | virtual void endIndexKey() = 0;␊ |
320 | virtual void startIndexValue(bool) = 0;␊ |
321 | virtual void endIndexValue(const char *,bool) = 0;␊ |
322 | virtual void startIndexItem(const char *ref,const char *file) = 0;␊ |
323 | virtual void endIndexItem(const char *ref,const char *file) = 0;␊ |
324 | virtual void startGroupHeader(int) = 0;␊ |
325 | virtual void endGroupHeader(int) = 0;␊ |
326 | virtual void startMemberSections() = 0;␊ |
327 | virtual void endMemberSections() = 0;␊ |
328 | virtual void startHeaderSection() = 0;␊ |
329 | virtual void endHeaderSection() = 0;␊ |
330 | virtual void startMemberHeader(const char *anchor) = 0;␊ |
331 | virtual void endMemberHeader() = 0;␊ |
332 | virtual void startMemberSubtitle() = 0;␊ |
333 | virtual void endMemberSubtitle() = 0;␊ |
334 | virtual void startMemberDocList() = 0;␊ |
335 | virtual void endMemberDocList() = 0;␊ |
336 | virtual void startMemberList() = 0;␊ |
337 | virtual void endMemberList() = 0;␊ |
338 | virtual void startInlineDescription() = 0;␊ |
339 | virtual void endInlineDescription() = 0;␊ |
340 | virtual void startInlineHeader() = 0;␊ |
341 | virtual void endInlineHeader() = 0;␊ |
342 | virtual void startAnonTypeScope(int) = 0;␊ |
343 | virtual void endAnonTypeScope(int) = 0;␊ |
344 | virtual void startMemberItem(int) = 0;␊ |
345 | virtual void endMemberItem() = 0;␊ |
346 | virtual void startMemberTemplateParams() = 0;␊ |
347 | virtual void endMemberTemplateParams() = 0;␊ |
348 | virtual void startMemberGroupHeader(bool) = 0;␊ |
349 | virtual void endMemberGroupHeader() = 0;␊ |
350 | virtual void startMemberGroupDocs() = 0;␊ |
351 | virtual void endMemberGroupDocs() = 0;␊ |
352 | virtual void startMemberGroup() = 0;␊ |
353 | virtual void endMemberGroup(bool) = 0;␊ |
354 | virtual void insertMemberAlign(bool) = 0;␊ |
355 | virtual void startMemberDoc(const char *,const char *,␊ |
356 | const char *,const char *,bool) = 0;␊ |
357 | virtual void endMemberDoc(bool) = 0;␊ |
358 | virtual void startDoxyAnchor(const char *fName,const char *manName,␊ |
359 | const char *anchor,const char *name,␊ |
360 | const char *args) = 0;␊ |
361 | virtual void endDoxyAnchor(const char *fileName,const char *anchor) = 0;␊ |
362 | virtual void writeLatexSpacing() = 0;␊ |
363 | virtual void writeStartAnnoItem(const char *type,const char *file,␊ |
364 | const char *path,const char *name) = 0;␊ |
365 | virtual void writeEndAnnoItem(const char *name) = 0;␊ |
366 | virtual void startMemberDescription() = 0;␊ |
367 | virtual void endMemberDescription() = 0;␊ |
368 | virtual void startIndent() = 0;␊ |
369 | virtual void endIndent() = 0;␊ |
370 | virtual void writeSynopsis() = 0;␊ |
371 | virtual void startClassDiagram() = 0;␊ |
372 | virtual void endClassDiagram(const ClassDiagram &,const char *,const char *) = 0;␊ |
373 | virtual void startDotGraph() = 0;␊ |
374 | virtual void endDotGraph(const DotClassGraph &g) = 0;␊ |
375 | virtual void startInclDepGraph() = 0;␊ |
376 | virtual void endInclDepGraph(const DotInclDepGraph &g) = 0;␊ |
377 | virtual void startGroupCollaboration() = 0;␊ |
378 | virtual void endGroupCollaboration(const DotGroupCollaboration &g) = 0;␊ |
379 | virtual void startCallGraph() = 0;␊ |
380 | virtual void endCallGraph(const DotCallGraph &g) = 0;␊ |
381 | virtual void startDirDepGraph() = 0;␊ |
382 | virtual void endDirDepGraph(const DotDirDeps &g) = 0;␊ |
383 | virtual void writeGraphicalHierarchy(const DotGfxHierarchyTable &g) = 0;␊ |
384 | virtual void startQuickIndices() = 0;␊ |
385 | virtual void endQuickIndices() = 0;␊ |
386 | virtual void writeSplitBar(const char *) = 0;␊ |
387 | virtual void writeLogo() = 0;␊ |
388 | virtual void writeQuickLinks(bool compact,HighlightedItem hli) = 0;␊ |
389 | virtual void startContents() = 0;␊ |
390 | virtual void endContents() = 0;␊ |
391 | virtual void startTextBlock(bool) = 0;␊ |
392 | virtual void endTextBlock(bool) = 0;␊ |
393 | virtual void lastIndexPage() = 0;␊ |
394 | virtual void startMemberDocPrefixItem() = 0;␊ |
395 | virtual void endMemberDocPrefixItem() = 0;␊ |
396 | virtual void startMemberDocName(bool) = 0;␊ |
397 | virtual void endMemberDocName() = 0;␊ |
398 | virtual void startParameterType(bool,const char *) = 0;␊ |
399 | virtual void endParameterType() = 0;␊ |
400 | virtual void startParameterName(bool) = 0;␊ |
401 | virtual void endParameterName(bool,bool,bool) = 0;␊ |
402 | virtual void startParameterList(bool) = 0;␊ |
403 | virtual void endParameterList() = 0;␊ |
404 | ␊ |
405 | virtual void startConstraintList(const char *) = 0;␊ |
406 | virtual void startConstraintParam() = 0;␊ |
407 | virtual void endConstraintParam() = 0;␊ |
408 | virtual void startConstraintType() = 0;␊ |
409 | virtual void endConstraintType() = 0;␊ |
410 | virtual void startConstraintDocs() = 0;␊ |
411 | virtual void endConstraintDocs() = 0;␊ |
412 | virtual void endConstraintList() = 0;␊ |
413 | ␊ |
414 | protected:␊ |
415 | FTextStream t;␊ |
416 | QFile *file;␊ |
417 | QCString fileName;␊ |
418 | QCString dir;␊ |
419 | bool active;␊ |
420 | QStack<bool> *genStack;␊ |
421 | ␊ |
422 | private:␊ |
423 | OutputGenerator(const OutputGenerator &o);␊ |
424 | OutputGenerator &operator=(const OutputGenerator &o);␊ |
425 | };␊ |
426 | ␊ |
427 | /*! \brief Interface used for generating documentation.␊ |
428 | *␊ |
429 | * This abstract class is used by several functions␊ |
430 | * to generate the output for a specific format. ␊ |
431 | * This interface contains some state saving and changing␊ |
432 | * functions for dealing with format specific output.␊ |
433 | */␊ |
434 | class OutputDocInterface : public BaseOutputDocInterface␊ |
435 | {␊ |
436 | public:␊ |
437 | virtual ~OutputDocInterface() {}␊ |
438 | ␊ |
439 | /*! Create a new output generator. This can later by appended␊ |
440 | * to the current one using append().␊ |
441 | */␊ |
442 | //virtual OutputDocInterface *clone() = 0;␊ |
443 | ␊ |
444 | /*! Disables all output formats except format \a o ␊ |
445 | * (useful for OutputList only) ␊ |
446 | */␊ |
447 | virtual void disableAllBut(OutputGenerator::OutputType o) = 0;␊ |
448 | ␊ |
449 | /*! Enables all output formats as far as they have been enabled in␊ |
450 | * the config file. (useful for OutputList only) ␊ |
451 | */␊ |
452 | virtual void enableAll() = 0;␊ |
453 | ␊ |
454 | /*! Disables all output formats (useful for OutputList only) */␊ |
455 | virtual void disableAll()= 0;␊ |
456 | ␊ |
457 | /*! Disables a specific output format (useful for OutputList only) */␊ |
458 | virtual void disable(OutputGenerator::OutputType o) = 0;␊ |
459 | ␊ |
460 | /*! Enables a specific output format (useful for OutputList only) */␊ |
461 | virtual void enable(OutputGenerator::OutputType o) = 0;␊ |
462 | ␊ |
463 | /*! Check whether a specific output format is currenly enabled ␊ |
464 | * (useful for OutputList only) ␊ |
465 | */␊ |
466 | virtual bool isEnabled(OutputGenerator::OutputType o) = 0;␊ |
467 | ␊ |
468 | /*! Appends the output generated by generator \a g to this␊ |
469 | * generator.␊ |
470 | */ ␊ |
471 | //virtual void append(const OutputDocInterface *g) = 0;␊ |
472 | ␊ |
473 | /*! Pushes the state of the current generator (or list of ␊ |
474 | * generators) on a stack.␊ |
475 | */␊ |
476 | virtual void pushGeneratorState() = 0;␊ |
477 | ␊ |
478 | /*! Pops the state of the current generator (or list of ␊ |
479 | * generators) on a stack. Should be preceded by a call␊ |
480 | * the pushGeneratorState().␊ |
481 | */␊ |
482 | virtual void popGeneratorState() = 0;␊ |
483 | };␊ |
484 | ␊ |
485 | ␊ |
486 | #endif␊ |
487 |