summaryrefslogtreecommitdiffstats
path: root/src/outputgen.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/outputgen.h')
-rw-r--r--src/outputgen.h405
1 files changed, 293 insertions, 112 deletions
diff --git a/src/outputgen.h b/src/outputgen.h
index 49bd734..12e4291 100644
--- a/src/outputgen.h
+++ b/src/outputgen.h
@@ -30,112 +30,150 @@ class DotClassGraph;
class DotInclDepGraph;
class DotGfxHierarchyTable;
-class OutputGenerator
+/*! \brief Base Interface used for generating documentation.
+ *
+ * This abstract class is used by the documentation block
+ * parser to generate the output for a specific format,
+ * or a list of formats (see OutputList). This interface
+ * contains functions that generate output.
+ */
+class BaseOutputDocInterface
{
public:
- enum OutputType { Html, Latex, Man, RTF, XML };
- OutputGenerator();
- virtual ~OutputGenerator();
+ /*! Start of a bullet list: e.g. \c <ul> in html. writeListItem() is
+ * Used for the bullet items.
+ */
+ virtual void startItemList() = 0;
- virtual OutputGenerator *copy() = 0;
- virtual void append(const OutputGenerator *) = 0;
- virtual void enable() = 0;
- virtual void disable() = 0;
- virtual void enableIf(OutputType o) = 0;
- virtual void disableIf(OutputType o) = 0;
- virtual void disableIfNot(OutputType o) = 0;
- virtual bool isEnabled(OutputType o) = 0;
- virtual OutputGenerator *get(OutputType o) = 0;
+ /*! Writes a list item for a bullet or enumerated
+ * list: e.g. \c <li> in html
+ */
+ virtual void writeListItem() = 0;
- virtual void startFile(const char *name,const char *title,bool ext) = 0;
- virtual void writeFooter(int,bool) = 0;
- virtual void endFile() = 0;
- virtual void startIndexSection(IndexSections) = 0;
- virtual void endIndexSection(IndexSections) = 0;
- virtual void startProjectNumber() = 0;
- virtual void endProjectNumber() = 0;
- virtual void writeStyleInfo(int part) = 0;
- virtual void startTitleHead(const char *) = 0;
- virtual void endTitleHead(const char *fileName,const char *name) = 0;
- virtual void startTitle() = 0;
- virtual void endTitle() = 0;
- virtual void newParagraph() = 0;
- virtual void writeString(const char *text) = 0;
- virtual void startIndexList() = 0;
- virtual void endIndexList() = 0;
- virtual void startItemList() = 0;
+ /*! Ends a bullet list: e.g. \c </ul> in html */
virtual void endItemList() = 0;
+
+ /*! Writes an ASCII string to the output. Converts characters that have
+ * A special meaning, like \c & in html.
+ */
+ virtual void docify(const char *s) = 0;
+
+ /*! Writes a single ASCII character to the output. Converts characters
+ * that have a special meaning.
+ */
+ virtual void writeChar(char c) = 0;
+
+ /*! Writes an ASCII string to the output, \e without converting
+ * special characters.
+ */
+ virtual void writeString(const char *text) = 0;
+
+ /*! Starts a new paragraph */
+ virtual void newParagraph() = 0;
+
+ /*! Starts a enumeration list: e.g. \c <ol> in html.
+ * writeListItem() is used for the items.
+ */
virtual void startEnumList() = 0;
+
+ /*! Ends an enumeration list: e.g. \c </ol> in html.
+ */
virtual void endEnumList() = 0;
- virtual void startBold() = 0;
- virtual void endBold() = 0;
- virtual void startAlphabeticalIndexList() = 0;
- virtual void endAlphabeticalIndexList() = 0;
- virtual void writeIndexHeading(const char *s) = 0;
- virtual void writeIndexItem(const char *ref,const char *file,
- const char *text) = 0;
- virtual void docify(const char *s) = 0;
- virtual void codify(const char *s) = 0;
+
+ /*! Writes a link to an object in the documentation.
+ * \param ref If this is non-zero, the object is to be found in
+ * an external documentation file.
+ * \param file The file in which the object is located.
+ * \param anchor The anchor uniquely identifying the object within
+ * the file.
+ * \param text The text to display as a placeholder for the link.
+ */
virtual void writeObjectLink(const char *ref,const char *file,
const char *anchor, const char *text) = 0;
+
+ /*! Writes a link to an object in a code fragment.
+ * \param ref If this is non-zero, the object is to be found in
+ * an external documentation file.
+ * \param file The file in which the object is located.
+ * \param anchor The anchor uniquely identifying the object within
+ * the file.
+ * \param text The text to display as a placeholder for the link.
+ */
virtual void writeCodeLink(const char *ref,const char *file,
const char *anchor,const char *text) = 0;
- virtual void startTextLink(const char *file,const char *anchor) = 0;
- virtual void endTextLink() = 0;
+
+ /*! Writes a (link to an) URL found in the documentation.
+ * \param url To URL to link to.
+ * \param text The text to display as a placeholder for the link.
+ */
virtual void writeHtmlLink(const char *url,const char *text) = 0;
+
+ /*! Writes a (link to an) email address found in the documentation.
+ * \param url To email address, this is also used for the link text.
+ */
virtual void writeMailLink(const char *url) = 0;
+
+ /*! Changes the text font to bold face. The bold section ends with
+ * endBold()
+ */
+ virtual void startBold() = 0;
+
+ /*! End a section of text displayed in bold face. */
+ virtual void endBold() = 0;
+
+ /*! Changes the text font to fixed size. The section ends with
+ * endTypewriter()
+ */
virtual void startTypewriter() = 0;
+
+ /*! End a section of text displayed in typewriter style. */
virtual void endTypewriter() = 0;
- virtual void startGroupHeader() = 0;
- virtual void endGroupHeader() = 0;
- virtual void writeListItem() = 0;
- virtual void startMemberSections() = 0;
- virtual void endMemberSections() = 0;
- virtual void startMemberHeader() = 0;
- virtual void endMemberHeader() = 0;
- virtual void startMemberSubtitle() = 0;
- virtual void endMemberSubtitle() = 0;
- virtual void startMemberList() = 0;
- virtual void endMemberList() = 0;
- virtual void startMemberItem(int) = 0;
- virtual void endMemberItem(bool) = 0;
- virtual void startMemberGroupHeader(bool) = 0;
- virtual void endMemberGroupHeader() = 0;
- virtual void startMemberGroupDocs() = 0;
- virtual void endMemberGroupDocs() = 0;
- virtual void startMemberGroup() = 0;
- virtual void endMemberGroup(bool) = 0;
- virtual void insertMemberAlign() = 0;
+ /*! Changes the text font to italic. The italic section ends with
+ * endEmphasis()
+ */
+ virtual void startEmphasis() = 0;
- virtual void writeRuler() = 0;
- virtual void writeAnchor(const char *fileName,const char *name) = 0;
+ /*! Ends a section of text displayed in italic. */
+ virtual void endEmphasis() = 0;
+
+ /*! Starts a source code fragment. The fragment will be
+ * fed to the code parser (see code.h) for syntax highlighting
+ * and cross-referencing. The fragment ends by a call to
+ * endCodeFragment()
+ */
virtual void startCodeFragment() = 0;
+
+ /*! Ends a source code fragment
+ */
virtual void endCodeFragment() = 0;
+
+ /*! Starts a fragment of preformatted text. This means that
+ * spacing, tabs and newlines should be kept in the output
+ */
+
virtual void startPreFragment() = 0;
+ /*! Ens a preformatted text fragment. */
+
virtual void endPreFragment() = 0;
- virtual void startCodeLine() = 0;
- virtual void endCodeLine() = 0;
- virtual void writeBoldString(const char *text) = 0;
- virtual void startEmphasis() = 0;
- virtual void endEmphasis() = 0;
- virtual void writeChar(char c) = 0;
- virtual void startMemberDoc(const char *,const char *,
- const char *,const char *) = 0;
- virtual void endMemberDoc() = 0;
- virtual void startDoxyAnchor(const char *fName,const char *anchor,
- const char *name) = 0;
- virtual void endDoxyAnchor(const char *fileName,const char *anchor) = 0;
- virtual void startCodeAnchor(const char *label) = 0;
- virtual void endCodeAnchor() = 0;
- virtual void writeLatexSpacing() = 0;
- virtual void writeStartAnnoItem(const char *type,const char *file,
- const char *path,const char *name) = 0;
- virtual void writeEndAnnoItem(const char *name) = 0;
+ /*! Writes a horizontal ruler to the output */
+ virtual void writeRuler() = 0;
+
+ /*! Starts a description list: e.g. \c <dl> in HTML
+ * Items are surrounded by startDescItem() and endDescItem()
+ */
virtual void startDescription() = 0;
+
+ /*! Ends a description list: e.g. \c </dl> in HTML */
virtual void endDescription() = 0;
+
+ /*! Starts an item of a description list: e.g. \c <dt> in HTML. */
virtual void startDescItem() = 0;
+
+ /*! Ends an item of a description list and starts the
+ * description itself: e.g. \c <dd> in HTML.
+ */
virtual void endDescItem() = 0;
virtual void startSubsection() = 0;
virtual void endSubsection() = 0;
@@ -164,52 +202,150 @@ class OutputGenerator
virtual void writeTilde(char) = 0;
virtual void writeRing(char) = 0;
virtual void writeSharpS() = 0;
- virtual void startMemberDescription() = 0;
- virtual void endMemberDescription() = 0;
virtual void startDescList() = 0;
+ virtual void endDescList() = 0;
virtual void endDescTitle() = 0;
virtual void writeDescItem() = 0;
- virtual void endDescList() = 0;
+ virtual void startTitle() = 0;
+ virtual void endTitle() = 0;
+ virtual void writeAnchor(const char *fileName,const char *name) = 0;
virtual void startSection(const char *,const char *,bool) = 0;
virtual void endSection(const char *,bool) = 0;
- virtual void writeSectionRef(const char *,const char *,const char *) = 0;
+ virtual void writeSectionRef(const char *,const char *,
+ const char *,const char *) = 0;
virtual void writeSectionRefItem(const char *,const char *,const char *) = 0;
- virtual void writeSectionRefAnchor(const char *,const char *,const char *) = 0;
virtual void lineBreak() = 0;
virtual void addIndexItem(const char *s1,const char *s2) = 0;
- virtual void startIndent() = 0;
- virtual void endIndent() = 0;
- virtual void writeSynopsis() = 0;
- virtual void startClassDiagram() = 0;
- virtual void endClassDiagram(ClassDiagram &,const char *,const char *) = 0;
- virtual void startColorFont(uchar r,uchar g,uchar b) = 0;
- virtual void endColorFont() = 0;
- virtual void startPageRef() = 0;
- virtual void endPageRef(const char *,const char *) = 0;
- virtual void startQuickIndexItem(const char *s,const char *l) = 0;
- virtual void endQuickIndexItem() = 0;
virtual void writeFormula(const char *,const char *) = 0;
virtual void writeNonBreakableSpace() = 0;
virtual void startImage(const char *,const char *,bool) = 0;
virtual void endImage(bool) = 0;
-
virtual void startDescTable() = 0;
virtual void endDescTable() = 0;
virtual void startDescTableTitle() = 0;
virtual void endDescTableTitle() = 0;
virtual void startDescTableData() = 0;
virtual void endDescTableData() = 0;
+ virtual void startTextLink(const char *file,const char *anchor) = 0;
+ virtual void endTextLink() = 0;
+ virtual void startPageRef() = 0;
+ virtual void endPageRef(const char *,const char *) = 0;
+
+
+ virtual void startCodeLine() = 0;
+ virtual void endCodeLine() = 0;
+ virtual void startCodeAnchor(const char *label) = 0;
+ virtual void endCodeAnchor() = 0;
+ virtual void startFontClass(const char *) = 0;
+ virtual void endFontClass() = 0;
+
+ /*! Writes an ASCII string to the output. This function should keep
+ * spaces visible, should break lines at a newline and should convert
+ * tabs to the right number of spaces.
+ */
+ virtual void codify(const char *s) = 0;
+
+};
+/*! \brief Abstract output generator.
+ *
+ * Subclass this class to add support for a new output format
+ */
+class OutputGenerator : public BaseOutputDocInterface
+{
+ public:
+ enum OutputType { Html, Latex, Man, RTF, XML };
+
+ OutputGenerator();
+ virtual ~OutputGenerator();
+
+ ///////////////////////////////////////////////////////////////
+ // generic generator methods
+ ///////////////////////////////////////////////////////////////
+ virtual OutputGenerator *copy() = 0;
+ virtual void append(const OutputGenerator *) = 0;
+ virtual void enable() = 0;
+ virtual void disable() = 0;
+ virtual void enableIf(OutputType o) = 0;
+ virtual void disableIf(OutputType o) = 0;
+ virtual void disableIfNot(OutputType o) = 0;
+ virtual bool isEnabled(OutputType o) = 0;
+ virtual OutputGenerator *get(OutputType o) = 0;
+ void clear() { b.close(); a.resize(0); b.setBuffer(a);
+ b.open(IO_WriteOnly); t.setDevice(&b); }
+ void startPlainFile(const char *name);
+ void endPlainFile();
+ QCString getContents() const;
+ bool isEnabled() const { return active; }
+ void pushGeneratorState();
+ void popGeneratorState();
+
+ ///////////////////////////////////////////////////////////////
+ // structural output interface
+ ///////////////////////////////////////////////////////////////
+ virtual void startFile(const char *name,const char *title,bool ext) = 0;
+ virtual void writeFooter(int,bool) = 0;
+ virtual void endFile() = 0;
+ virtual void startIndexSection(IndexSections) = 0;
+ virtual void endIndexSection(IndexSections) = 0;
+ virtual void startProjectNumber() = 0;
+ virtual void endProjectNumber() = 0;
+ virtual void writeStyleInfo(int part) = 0;
+ virtual void startTitleHead(const char *) = 0;
+ virtual void endTitleHead(const char *fileName,const char *name) = 0;
+ virtual void startIndexList() = 0;
+ virtual void endIndexList() = 0;
+ virtual void startAlphabeticalIndexList() = 0;
+ virtual void endAlphabeticalIndexList() = 0;
+ virtual void writeIndexHeading(const char *s) = 0;
+ virtual void writeIndexItem(const char *ref,const char *file,
+ const char *text) = 0;
+ virtual void startGroupHeader() = 0;
+ virtual void endGroupHeader() = 0;
+ virtual void startMemberSections() = 0;
+ virtual void endMemberSections() = 0;
+ virtual void startMemberHeader() = 0;
+ virtual void endMemberHeader() = 0;
+ virtual void startMemberSubtitle() = 0;
+ virtual void endMemberSubtitle() = 0;
+ virtual void startMemberList() = 0;
+ virtual void endMemberList() = 0;
+ virtual void startMemberItem(int) = 0;
+ virtual void endMemberItem(bool) = 0;
+ virtual void startMemberGroupHeader(bool) = 0;
+ virtual void endMemberGroupHeader() = 0;
+ virtual void startMemberGroupDocs() = 0;
+ virtual void endMemberGroupDocs() = 0;
+ virtual void startMemberGroup() = 0;
+ virtual void endMemberGroup(bool) = 0;
+ virtual void insertMemberAlign() = 0;
+ virtual void startMemberDoc(const char *,const char *,
+ const char *,const char *) = 0;
+ virtual void endMemberDoc() = 0;
+ virtual void startDoxyAnchor(const char *fName,const char *anchor,
+ const char *name) = 0;
+ virtual void endDoxyAnchor(const char *fileName,const char *anchor) = 0;
+ virtual void writeLatexSpacing() = 0;
+ virtual void writeStartAnnoItem(const char *type,const char *file,
+ const char *path,const char *name) = 0;
+ virtual void writeEndAnnoItem(const char *name) = 0;
+ virtual void startMemberDescription() = 0;
+ virtual void endMemberDescription() = 0;
+ virtual void startIndent() = 0;
+ virtual void endIndent() = 0;
+ virtual void writeSynopsis() = 0;
+ virtual void startClassDiagram() = 0;
+ virtual void endClassDiagram(ClassDiagram &,const char *,const char *) = 0;
virtual void startDotGraph() = 0;
virtual void endDotGraph(DotClassGraph &g) = 0;
virtual void startInclDepGraph() = 0;
virtual void endInclDepGraph(DotInclDepGraph &g) = 0;
virtual void writeGraphicalHierarchy(DotGfxHierarchyTable &g) = 0;
-
+ virtual void startQuickIndexItem(const char *s,const char *l) = 0;
+ virtual void endQuickIndexItem() = 0;
virtual void startTextBlock(bool) = 0;
virtual void endTextBlock() = 0;
virtual void lastIndexPage() = 0;
-
virtual void startMemberDocPrefixItem() = 0;
virtual void endMemberDocPrefixItem() = 0;
virtual void startMemberDocName() = 0;
@@ -217,18 +353,6 @@ class OutputGenerator
virtual void startParameter(bool) = 0;
virtual void endParameter(bool) = 0;
- virtual void startFontClass(const char *) = 0;
- virtual void endFontClass() = 0;
-
-
- void clear() { b.close(); a.resize(0); b.setBuffer(a);
- b.open(IO_WriteOnly); t.setDevice(&b); }
- void startPlainFile(const char *name);
- void endPlainFile();
- QCString getContents() const;
- bool isEnabled() const { return active; }
- void pushGeneratorState();
- void popGeneratorState();
protected:
QTextStream fs;
QByteArray a;
@@ -244,4 +368,61 @@ class OutputGenerator
QStack<bool> *genStack;
};
+/*! \brief Base Interface used for generating documentation.
+ *
+ * This abstract class is used by the documentation block
+ * parser to generate the output for a specific format.
+ * This interface contains some state saving and changing
+ * functions for dealing with format specific output.
+ */
+class OutputDocInterface : public BaseOutputDocInterface
+{
+ public:
+ /*! Create a new output generator. This can later by appended
+ * to the current one using append().
+ */
+ virtual OutputDocInterface *clone() = 0;
+
+ /*! Disables all output formats except format \a o
+ * (useful for OutputList only)
+ */
+ virtual void disableAllBut(OutputGenerator::OutputType o) = 0;
+
+ /*! Enables all output formats as far as they have been enabled in
+ * the config file. (useful for OutputList only)
+ */
+ virtual void enableAll() = 0;
+
+ /*! Disables all output formats (useful for OutputList only) */
+ virtual void disableAll()= 0;
+
+ /*! Disables a specific output format (useful for OutputList only) */
+ virtual void disable(OutputGenerator::OutputType o) = 0;
+
+ /*! Enables a specific output format (useful for OutputList only) */
+ virtual void enable(OutputGenerator::OutputType o) = 0;
+
+ /*! Check whether a specific output format is currenly enabled
+ * (useful for OutputList only)
+ */
+ virtual bool isEnabled(OutputGenerator::OutputType o) = 0;
+
+ /*! Appends the output generated by generator \a g to this
+ * generator.
+ */
+ virtual void append(const OutputDocInterface *g) = 0;
+
+ /*! Pushes the state of the current generator (or list of
+ * generators) on a stack.
+ */
+ virtual void pushGeneratorState() = 0;
+
+ /*! Pops the state of the current generator (or list of
+ * generators) on a stack. Should be preceded by a call
+ * the pushGeneratorState().
+ */
+ virtual void popGeneratorState() = 0;
+};
+
+
#endif
generated by cgit v0.12 at 2024-11-09 12:59:10 (GMT)