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
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
|
/* -----------------------------------------------------------------------------
* This file is part of SWIG, which is licensed as a whole under version 3
* (or any later version) of the GNU General Public License. Some additional
* terms also apply to certain portions of SWIG. The full details of the SWIG
* license and copyrights can be found in the LICENSE and COPYRIGHT files
* included with the SWIG source code as distributed by the SWIG developers
* and at https://www.swig.org/legal.html.
*
* pydoc.h
*
* Module to return documentation for nodes formatted for PyDoc
* ----------------------------------------------------------------------------- */
#ifndef SWIG_PYDOC_H
#define SWIG_PYDOC_H
#include <list>
#include <string>
#include "swig.h"
#include "doxyentity.h"
#include "doxytranslator.h"
#define DOC_STRING_LENGTH 64 // characters per line allowed
#define DOC_PARAM_STRING_LENGTH 30 // characters reserved for param name / type
class PyDocConverter : public DoxygenTranslator {
public:
PyDocConverter(int flags = 0);
String *makeDocumentation(Node *node);
protected:
size_t m_tableLineLen;
bool m_prevRowIsTH;
std::string m_url;
/*
* Translate every entity in a tree, also manages sections
* display. Prints title for every group of tags that have
* a section title associated with them
*/
std::string translateSubtree(DoxygenEntity &doxygenEntity);
/*
* Translate one entity with the appropriate handler, according
* to the tagHandlers
*/
void translateEntity(DoxygenEntity &doxyEntity, std::string &translatedComment);
/*
* Typedef for the function that handles one tag
* arg - some string argument to easily pass it through lookup table
*/
typedef void (PyDocConverter::*tagHandler) (DoxygenEntity &tag, std::string &translatedComment, const std::string &arg);
/*
* Wrap the command data with the some string
* arg - string to wrap with, like '_' or '*'
*/
void handleTagWrap(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg);
/*
* Just prints new line
*/
void handleNewLine(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg);
/*
* Print the name of tag to the output, used for escape-commands
*/
void handleTagChar(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg);
/*
* Format the contents of the \exception tag or its synonyms.
*/
void handleTagException(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg);
/*
* Print only the content and strip original tag
*/
void handleParagraph(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg = std::string());
/*
* Handle Doxygen verbatim tag
*/
void handleVerbatimBlock(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg = std::string());
/*
* Handle one of the Doxygen formula-related tags.
*/
void handleMath(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg);
/*
* Handle a code snippet.
*/
void handleCode(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg);
/*
* Print only data part of code
*/
void handlePlainString(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg);
/**
* Copies verbatim args of the tag to output, used for commands like \f$, ...
*/
void handleTagVerbatim(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg);
/*
* Print the if-elseif-else-endif section
*/
void handleTagIf(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg);
/*
* Prints the specified message, than the contents of the tag
* arg - message
*/
void handleTagMessage(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg);
/*
* Insert 'Title: ...'
*/
void handleTagPar(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg);
/*
* Insert 'Image: ...'
*/
void handleTagImage(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg);
/*
* Format nice param description with type information
*/
void handleTagParam(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg);
/*
* Format the contents of the \return tag or its synonyms.
*/
void handleTagReturn(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg);
/*
* Writes text for \ref tag.
*/
void handleTagRef(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg);
/* Handles HTML tags recognized by Doxygen, like <A ...>, <ul>, <table>, ... */
void handleDoxyHtmlTag(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg);
/** Does not output params of HTML tag, for example in <table border='1'>
* 'border=1' is not written to output.
*/
void handleDoxyHtmlTagNoParam(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg);
/** Translates tag <a href = "url">text</a> to: text ("url"). */
void handleDoxyHtmlTag_A(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg);
/*
* Handles HTML tags, which are translated to markdown-like syntax, for example
* <i>text</i> --> _text_. Appends arg for start HTML tag and end HTML tag.
*/
void handleDoxyHtmlTag2(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg);
/* Handles HTML table, tag <tr> */
void handleDoxyHtmlTag_tr(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg);
/* Handles HTML table, tag <th> */
void handleDoxyHtmlTag_th(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg);
/* Handles HTML table, tag <td> */
void handleDoxyHtmlTag_td(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg);
/* Handles HTML entities recognized by Doxygen, like <, ©, ... */
void handleHtmlEntity(DoxygenEntity &, std::string &translatedComment, const std::string &arg);
/*
* Simple helper function that calculates correct parameter type
* of the node stored in 'currentNode'
* If param with specified name is not found, empty string is returned
*/
std::string getParamType(std::string name);
/*
* Simple helper function to retrieve the parameter value
*/
std::string getParamValue(std::string name);
private:
// temporary thing, should be refactored somehow
Node *currentNode;
// Extra indent for the current paragraph, must be output after each new line.
std::string m_indent;
// this contains the handler pointer and one string argument
typedef std::map<std::string, std::pair<tagHandler, std::string> >TagHandlersMap;
static TagHandlersMap tagHandlers;
// this contains the sections titles, like 'Arguments:' or 'Notes:', that are printed only once
static std::map<std::string, std::string> sectionTitles;
// Helper functions for fillStaticTables(): make a new tag handler object.
TagHandlersMap::mapped_type make_handler(tagHandler handler);
TagHandlersMap::mapped_type make_handler(tagHandler handler, const char *arg);
void fillStaticTables();
};
#endif
|
