source: trunk/tools/qdoc3/javadocgenerator.cpp@ 1030

Last change on this file since 1030 was 846, checked in by Dmitry A. Kuminov, 14 years ago

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.
File size: 14.1 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4** All rights reserved.
5** Contact: Nokia Corporation ([email protected])
6**
7** This file is part of the tools applications of the Qt Toolkit.
8**
9** $QT_BEGIN_LICENSE:LGPL$
10** Commercial Usage
11** Licensees holding valid Qt Commercial licenses may use this file in
12** accordance with the Qt Commercial License Agreement provided with the
13** Software or, alternatively, in accordance with the terms contained in
14** a written agreement between you and Nokia.
15**
16** GNU Lesser General Public License Usage
17** Alternatively, this file may be used under the terms of the GNU Lesser
18** General Public License version 2.1 as published by the Free Software
19** Foundation and appearing in the file LICENSE.LGPL included in the
20** packaging of this file. Please review the following information to
21** ensure the GNU Lesser General Public License version 2.1 requirements
22** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
23**
24** In addition, as a special exception, Nokia gives you certain additional
25** rights. These rights are described in the Nokia Qt LGPL Exception
26** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
27**
28** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file. Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you have questions regarding the use of this file, please contact
37** Nokia at [email protected].
38** $QT_END_LICENSE$
39**
40****************************************************************************/
41
42#include "javadocgenerator.h"
43
44QT_BEGIN_NAMESPACE
45
46enum JavaSignatureSyntax {
47 GeneratedJdocFile,
48 JavadocRef,
49 SlotSignature
50};
51
52static QString javaSignature(const FunctionNode *func, JavaSignatureSyntax syntax,
53 int maxParams = 65535)
54{
55 maxParams = qMin(maxParams, func->parameters().count());
56
57 QString result;
58
59 if (syntax == GeneratedJdocFile) {
60 if (func->access() == Node::Public) {
61 result += "public ";
62 } else if (func->access() == Node::Protected) {
63 result += "protected ";
64 } else {
65 result += "private ";
66 }
67
68 if (func->metaness() == FunctionNode::Native)
69 result += "native ";
70
71 if (func->isConst())
72 result += "final ";
73
74 // ### func->metaness() == FunctionNode::Abstract
75
76 if (func->isStatic())
77 result += "static ";
78
79 if (!func->returnType().isEmpty()) {
80 result += func->returnType();
81 result += ' ';
82 }
83 }
84
85 if (syntax == SlotSignature) {
86 result += "void mySlot";
87 } else {
88 result += func->name();
89 }
90 result += '(';
91 for (int i = 0; i < maxParams; ++i) {
92 if (i != 0)
93 result += ", ";
94 result += func->parameters().at(i).leftType();
95 if (syntax != JavadocRef) {
96 result += ' ';
97 result += func->parameters().at(i).name();
98 }
99 }
100 result += ')';
101
102 return result;
103}
104
105static QString packageName(const Node *node)
106{
107 while (node && node->type() != Node::Class && node->type() != Node::Fake)
108 node = node->parent();
109 if (!node)
110 return QString();
111 return node->moduleName();
112}
113
114JavadocGenerator::JavadocGenerator()
115 : oldDevice(0), currentDepth(0)
116{
117}
118
119JavadocGenerator::~JavadocGenerator()
120{
121}
122
123void JavadocGenerator::initializeGenerator(const Config &config)
124{
125 HtmlGenerator::initializeGenerator(config);
126
127 formattingLeftMap().insert(ATOM_FORMATTING_PARAMETER,
128 formattingLeftMap().value(ATOM_FORMATTING_TELETYPE));
129 formattingRightMap().insert(ATOM_FORMATTING_PARAMETER,
130 formattingRightMap().value(ATOM_FORMATTING_TELETYPE));
131}
132
133void JavadocGenerator::terminateGenerator()
134{
135 HtmlGenerator::terminateGenerator();
136}
137
138QString JavadocGenerator::format()
139{
140 return "javadoc";
141}
142
143void JavadocGenerator::generateTree(const Tree *tree, CodeMarker *marker)
144{
145 HtmlGenerator::generateTree(tree, marker);
146}
147
148QString JavadocGenerator::fileExtension(const Node *node) const
149{
150 if (node->type() == Node::Fake) {
151 return "html";
152 } else {
153 return "jdoc";
154 }
155}
156
157QString JavadocGenerator::typeString(const Node *node)
158{
159 if (node->type() == Node::Function) {
160 const FunctionNode *func = static_cast<const FunctionNode *>(node);
161 return func->metaness() == FunctionNode::Signal ? "signal" : "method";
162 } else {
163 return HtmlGenerator::typeString(node);
164 }
165}
166
167QString JavadocGenerator::imageFileName(const Node *relative, const QString& fileBase)
168{
169 QString result = HtmlGenerator::imageFileName(relative, fileBase);
170 if (!result.isEmpty()) {
171 QString package = packageName(relative);
172 int numSubPackages = package.count('.') - 2;
173 while (numSubPackages > 0) {
174 result.prepend("%2E%2E/"); // javadoc 1.5.0_06 chokes on '../'
175 --numSubPackages;
176 }
177 }
178 return result;
179}
180
181static int textDepth = 0;
182
183void JavadocGenerator::startText(const Node *relative, CodeMarker *marker)
184{
185 if (textDepth++ == 0 && relative->type() != Node::Fake) {
186 Q_ASSERT(!oldDevice);
187 oldDevice = out().device();
188 Q_ASSERT(oldDevice);
189 out().setString(&buffer);
190 }
191 HtmlGenerator::startText(relative, marker);
192}
193
194void JavadocGenerator::endText(const Node *relative, CodeMarker *marker)
195{
196 HtmlGenerator::endText(relative, marker);
197 if (--textDepth == 0 && relative->type() != Node::Fake) {
198 Q_ASSERT(oldDevice);
199 out().setDevice(oldDevice);
200 oldDevice = 0;
201
202 /*
203 Need to escape XML metacharacters in .jdoc files.
204 */
205 buffer.replace("*/", "*&lt;!-- noop --&gt;/");
206 buffer.replace("&", "&amp;");
207 buffer.replace("\"", "&quot;");
208 buffer.replace("<", "&lt;");
209 buffer.replace(">", "&gt;");
210 out() << buffer;
211 buffer.clear();
212 }
213}
214
215int JavadocGenerator::generateAtom(const Atom *atom, const Node *relative, CodeMarker *marker)
216{
217 return HtmlGenerator::generateAtom(atom, relative, marker);
218}
219
220void JavadocGenerator::generateClassLikeNode(const InnerNode *inner, CodeMarker *marker)
221{
222 generateIndent();
223 out() << "<class name=\"" << protect(inner->name()) << "\"";
224 generateDoc(inner, marker);
225 out() << ">\n";
226
227 ++currentDepth;
228 foreach (Node *node, inner->childNodes()) {
229 if (node->isInnerNode()) {
230 generateClassLikeNode(static_cast<InnerNode *>(node), marker);
231 } else {
232 if (node->type() == Node::Enum) {
233 EnumNode *enume = static_cast<EnumNode *>(node);
234
235 generateIndent();
236 out() << "<enum name=\"" << protect(node->name()) << "\"";
237 generateDoc(node, marker);
238 out() << ">\n";
239
240 ++currentDepth;
241 const QList<EnumItem> &items = enume->items();
242 for (int i = 0; i < items.count(); ++i) {
243 const EnumItem &item = items.at(i);
244 generateIndent();
245 out() << "<enum-value name=\"" << protect(item.name()) << "\"";
246 generateEnumItemDoc(item.text(), enume, marker);
247 out() << "/>\n";
248 }
249 --currentDepth;
250
251 out() << "</enum>\n";
252 } else if (node->type() == Node::Function) {
253 FunctionNode *func = static_cast<FunctionNode *>(node);
254 generateIndent();
255 out() << (func->metaness() == FunctionNode::Signal ? "<signal" : "<method")
256 << " name=\""
257 << protect(javaSignature(func, GeneratedJdocFile))
258 << "\"";
259 generateDoc(node, marker);
260 out() << "/>\n";
261 }
262 }
263 }
264 --currentDepth;
265
266 generateIndent();
267 out() << "</class>\n";
268}
269
270void JavadocGenerator::generateFakeNode(const FakeNode *fake, CodeMarker *marker)
271{
272 HtmlGenerator::generateFakeNode(fake, marker);
273}
274
275bool JavadocGenerator::generateText(const Text& text, const Node *relative, CodeMarker *marker)
276{
277 HtmlGenerator::generateText(text, relative, marker);
278 return true;
279}
280
281void JavadocGenerator::generateBody(const Node *node, CodeMarker *marker)
282{
283 generateText(node->doc().body(), node, marker);
284}
285
286void JavadocGenerator::generateAlsoList( const Node *node, CodeMarker *marker )
287{
288 QList<Text> alsoList = node->doc().alsoList();
289 supplementAlsoList(node, alsoList);
290
291 if (node->type() == Node::Fake
292 || (node->type() == Node::Function
293 && static_cast<const FunctionNode *>(node)->metaness() == FunctionNode::Signal)) {
294 Text text;
295
296 if (!alsoList.isEmpty()) {
297 text << Atom(Atom::ListLeft, ATOM_LIST_TAG)
298 << Atom(Atom::ListTagLeft, ATOM_LIST_TAG)
299 << Atom(Atom::FormattingLeft, ATOM_FORMATTING_BOLD)
300 << "See Also:"
301 << Atom(Atom::FormattingRight, ATOM_FORMATTING_BOLD)
302 << Atom(Atom::ListTagRight, ATOM_LIST_TAG)
303 << Atom(Atom::ListItemLeft, ATOM_LIST_TAG);
304
305 for (int i = 0; i < alsoList.count(); ++i) {
306 if (i != 0)
307 text << ", ";
308 text << alsoList.at(i);
309 }
310 text << Atom(Atom::ListItemRight, ATOM_LIST_TAG)
311 << Atom(Atom::ListRight, ATOM_LIST_TAG);
312 }
313
314 generateText(text, node, marker);
315 } else {
316 foreach (const Text &text, alsoList) {
317 out() << "\n@see ";
318 generateText(text, node, marker);
319 }
320 }
321}
322
323QString JavadocGenerator::refForNode( const Node *node )
324{
325 if (node->type() == Node::Function)
326 return javaSignature(static_cast<const FunctionNode *>(node), JavadocRef);
327
328 return HtmlGenerator::refForNode(node);
329}
330
331QString JavadocGenerator::linkForNode( const Node *node, const Node *relative )
332{
333 // ### EVIL, relative should never be null
334 if (!relative)
335 relative = node;
336
337 if (packageName(node).isEmpty()) {
338 // ### jasmin: Fixme
339 return QString();
340 }
341
342 QString result;
343 if (node->type() == Node::Fake) {
344 result = node->name();
345 } else {
346 if (!node->isInnerNode()) {
347 result = linkForNode(node->parent(), relative) + "#" + refForNode(node);
348 } else {
349 result = node->name() + ".html";
350 }
351 }
352
353 QStringList nodePackage = packageName(node).split(".");
354 QStringList relativePackage = packageName(relative).split(".");
355 if (nodePackage == QStringList(QString()) || relativePackage == QStringList(QString())) {
356 qWarning("I'm in trouble [%s][%s]", qPrintable(node->name()), qPrintable(relative->name()));
357 return QString();
358 }
359
360 int i = nodePackage.count() - 1;
361 while (nodePackage.value(i) != relativePackage.value(i)) {
362 result.prepend(nodePackage.at(i) + "/");
363 --i;
364 }
365
366 ++i;
367 while (i < relativePackage.count()) {
368 result.prepend("%2E%2E/"); // javadoc 1.5.0_06 chokes on '../'
369 ++i;
370 }
371
372 return result;
373}
374
375QString JavadocGenerator::refForAtom(Atom *atom, const Node *node)
376{
377 return HtmlGenerator::refForAtom(atom, node);
378}
379
380/*
381 Neutralize dumb functions called from HtmlGenerator.
382*/
383void JavadocGenerator::generateDcf(const QString & /* fileBase */, const QString & /* startPage */,
384 const QString & /* title */, DcfSection & /* dcfRoot */)
385{
386}
387
388void JavadocGenerator::generateIndex(const QString & /* fileBase */, const QString & /* url */,
389 const QString & /* title */)
390{
391}
392
393void JavadocGenerator::generateIndent()
394{
395 for (int i = 0; i < currentDepth; ++i)
396 out() << " ";
397}
398
399void JavadocGenerator::generateDoc(const Node *node, CodeMarker *marker)
400{
401 const Text &text = node->doc().body();
402 if (!text.isEmpty()) {
403 out() << " doc=\"/**\n";
404 Generator::generateStatus(node, marker);
405 generateText(text, node, marker);
406 if (node && node->type() == Node::Function) {
407 const FunctionNode *func = static_cast<const FunctionNode *>(node);
408 if (func->metaness() == FunctionNode::Signal) {
409 QStringList slotSignatures;
410 for (int i = func->parameters().count(); i >= 0; --i)
411 slotSignatures += javaSignature(func, SlotSignature, i);
412
413 Text text;
414
415 text << Atom(Atom::ListLeft, ATOM_LIST_TAG)
416 << Atom(Atom::ListTagLeft, ATOM_LIST_TAG)
417 << Atom(Atom::FormattingLeft, ATOM_FORMATTING_BOLD);
418
419 if (slotSignatures.count() == 1) {
420 text << "Compatible Slot Signature:";
421 } else {
422 text << "Compatible Slot Signatures:";
423 }
424
425 text << Atom(Atom::FormattingRight, ATOM_FORMATTING_BOLD)
426 << Atom(Atom::ListTagRight, ATOM_LIST_TAG);
427
428 for (int i = 0; i < slotSignatures.count(); ++i) {
429 text << Atom(Atom::ListItemLeft, ATOM_LIST_TAG)
430 << Atom(Atom::C, marker->markedUpCode(slotSignatures.at(i), 0, ""))
431 << Atom(Atom::ListItemRight, ATOM_LIST_TAG);
432 }
433 text << Atom(Atom::ListRight, ATOM_LIST_TAG);
434 generateText(text, node, marker);
435 }
436 }
437 if (node)
438 generateAlsoList(node, marker);
439 out() << " */\"";
440 }
441}
442
443void JavadocGenerator::generateEnumItemDoc(const Text &text, const Node *node, CodeMarker *marker)
444{
445 out() << " doc=\"/**\n";
446 if (text.isEmpty()) {
447 out() << "Internal.";
448 } else {
449 generateText(text, node, marker);
450 }
451 out() << " */\"";
452}
453
454QT_END_NAMESPACE
Note: See TracBrowser for help on using the repository browser.