/**************************************************************************** ** ** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the Qt Script Generator project on Qt Labs. ** ** $QT_BEGIN_LICENSE:LGPL$ ** Commercial License Usage ** Licensees holding valid commercial Qt licenses may use this file in ** accordance with the commercial license agreement provided with the ** Software or, alternatively, in accordance with the terms contained in ** a written agreement between you and Digia. For licensing terms and ** conditions see http://qt.digia.com/licensing. For further information ** use the contact form at http://qt.digia.com/contact-us. ** ** GNU Lesser General Public License Usage ** Alternatively, this file may be used under the terms of the GNU Lesser ** General Public License version 2.1 as published by the Free Software ** Foundation and appearing in the file LICENSE.LGPL included in the ** packaging of this file. Please review the following information to ** ensure the GNU Lesser General Public License version 2.1 requirements ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. ** ** In addition, as a special exception, Digia gives you certain additional ** rights. These rights are described in the Digia Qt LGPL Exception ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. ** ** GNU General Public License Usage ** Alternatively, this file may be used under the terms of the GNU ** General Public License version 3.0 as published by the Free Software ** Foundation and appearing in the file LICENSE.GPL included in the ** packaging of this file. Please review the following information to ** ensure the GNU General Public License version 3.0 requirements will be ** met: http://www.gnu.org/copyleft/gpl.html. ** ** ** $QT_END_LICENSE$ ** ****************************************************************************/ #include "docgenerator.h" #include "fileout.h" DocGenerator::DocGenerator() { } QString DocGenerator::fileNameForClass(const AbstractMetaClass *meta_class) const { return QString::fromLatin1("%0.html").arg(meta_class->name().toLower()); } QString DocGenerator::subDirectoryForClass(const AbstractMetaClass *) const { return QString::fromLatin1("doc"); } static void writeDocumentHeader(QTextStream &s, const QString &title) { s << "" << endl << "" << endl << "" << endl << "" << endl << " " << title << "" << endl << " " << endl << "" << endl << "" << endl; } static void writeDocumentFooter(QTextStream &s) { s << "" << endl << "" << endl; } static bool classLessThan(const AbstractMetaClass *c1, const AbstractMetaClass *c2) { return c1->name() < c2->name(); } bool DocGenerator::shouldGenerate(const AbstractMetaClass *meta_class) const { uint cg = meta_class->typeEntry()->codeGeneration(); return (cg & TypeEntry::GenerateCode) != 0; } void DocGenerator::generate() { Generator::generate(); QHash > packHash; for (int i = 0; i < m_classes.size(); ++i) { const AbstractMetaClass *cls = m_classes.at(i); packHash[cls->package()].append(cls); } // package pages QHash >::const_iterator it; for (it = packHash.constBegin(); it != packHash.constEnd(); ++it) { QString package = it.key(); QList classesInPackage = it.value(); qSort(classesInPackage.begin(), classesInPackage.end(), classLessThan); FileOut file(m_out_dir + "/doc/" + package.split(".").join("_") + ".html"); writeDocumentHeader(file.stream, package + " Package"); file.stream << "

" << package << " Package

" << endl; file.stream << "

Classes

" << endl << "

" << endl; for (int i = 0; i < classesInPackage.size(); ++i) { const AbstractMetaClass *cls = classesInPackage.at(i); if (cls->name() == "Global") continue; /// ### fixme file.stream << "" << endl; } file.stream << "
" << cls->name() << "

" << endl; writeDocumentFooter(file.stream); } // all classes page { FileOut file(m_out_dir + "/doc/classes.html"); writeDocumentHeader(file.stream, "Classes"); file.stream << "

Classes

" << endl << "

" << endl; AbstractMetaClassList sortedClasses = m_classes; qSort(sortedClasses.begin(), sortedClasses.end(), classLessThan); for (int i = 0; i < sortedClasses.size(); ++i) { const AbstractMetaClass *cls = sortedClasses.at(i); if (cls->name() == "Global") continue; /// ### fixme file.stream << "" << endl; } file.stream << "
" << cls->name() << "

" << endl; writeDocumentFooter(file.stream); } // index.html { FileOut file(m_out_dir + "/doc/index.html"); writeDocumentHeader(file.stream, "Qt Bindings Reference Documentation"); file.stream << "

Qt Script Qt Bindings Reference Documentation

" << endl; file.stream << "

Packages

" << endl; file.stream << "
    " << endl; QStringList sortedPackages = packHash.keys(); qSort(sortedPackages.begin(), sortedPackages.end()); for (int i = 0; i < sortedPackages.size(); ++i) { QString pkg = sortedPackages.at(i); file.stream << "
  • " << pkg << "
    • " << endl; } file.stream << "
" << endl; file.stream << "

All Classes

" << endl; file.stream << "

Examples

" << endl; file.stream << "

Getting Started

" << endl << "

Using the Qt API in Qt Script is very similar to C++." << endl << "

var f = new QFile(\"foo.txt\");
" << endl << "C++ enum values are mapped to properties of the script constructor function; e.g. " << endl << "QIODevice::ReadOnly becomes QIODevice.ReadOnly.

" << endl << "
f.open(new QIODevice.OpenMode(QIODevice.ReadOnly));
" << endl << "

Each C++ flag type is mapped to a property of the script constructor function; e.g. " << endl << "QIODevice::OpenMode becomes QIODevice.OpenMode. Such a property is a constructor function " << endl << "that takes one or more enum values and constructs a flags instance by OR'ing the arguments " << endl << "together.

" << endl << "
var ts = new QTextStream(f);" << endl
                    << "ts.writeString(\"Boo\");
" << endl << "

C++ streaming operators are normally mapped to readT() and writeT() functions.

" << endl << "
f.close();
" << endl << "

In Qt Script, all objects are allocated on the heap; objects that are no longer " << endl << "referenced are garbage collected sometime in the future; therefore, make sure to " << endl << "explicitly free up resources if you can. (Without the call to close(), the underlying " << endl << "file would remain open until the file object is garbage collected.)

" << endl ; file.stream << "

Qt Reference Documentation

" << endl; writeDocumentFooter(file.stream); } } static bool shouldIgnoreEnum(const AbstractMetaEnum *enom) { return !enom->wasPublic() || (enom->name() == "enum_1"); } // in classgenerator.cpp void findPrototypeAndStaticFunctions( const AbstractMetaClass *meta_class, QMap &nameToPrototypeFunctions, QMap &nameToStaticFunctions); QList uniqueEnumValueIndexes(const AbstractMetaEnumValueList &values); static void writeFunction(QTextStream &s, const AbstractMetaFunction *fun) { s << "
  • " << fun->targetLangSignature() << "
    • " << endl; } void DocGenerator::write(QTextStream &s, const AbstractMetaClass *meta_class) { QString title = meta_class->name(); title.append(" "); if (meta_class->isNamespace()) title.append("Namespace"); else title.append("Class"); title.append(" Reference"); writeDocumentHeader(s, title); s << "

    " << title << "

    " << endl; s << "

    [package().split(".").join("_") << ".html"; s << "\">"; s << meta_class->package(); s << " package]

    " << endl; if (meta_class->baseClass()) { s << "

    Inherits baseClass()) << "\">" << meta_class->baseClass()->name() << ".

    " << endl; } else if (!meta_class->interfaces().isEmpty()) { AbstractMetaClass *iface = meta_class->interfaces().first(); AbstractMetaClass *impl = iface->primaryInterfaceImplementor(); if (impl != meta_class) { s << "

    Inherits " << impl->name() << ".

    " << endl; } } AbstractMetaFunctionList ctors; ctors = meta_class->queryFunctions(AbstractMetaClass::Constructors | AbstractMetaClass::WasPublic | AbstractMetaClass::NotRemovedFromTargetLang); QMap nameToPrototypeFunctions; QMap nameToStaticFunctions; findPrototypeAndStaticFunctions(meta_class, nameToPrototypeFunctions, nameToStaticFunctions); s << "

    Constructor

    " << endl; if (!ctors.isEmpty()) { s << "
      " << endl; for (int i = 0; i < ctors.size(); ++i) { writeFunction(s, ctors.at(i)); } s << "
    " << endl; } else { s << "

    This class has no public constructors. Calling the constructor function will cause a TypeError.

    "; } s << "

    Constructor Properties

    " << endl; s << "
      " << endl; s << "
    • prototype: The " << meta_class->name() << " prototype object
      • " << endl; if (!nameToStaticFunctions.isEmpty()) { QMap::const_iterator it; for (it = nameToStaticFunctions.constBegin(); it != nameToStaticFunctions.constEnd(); ++it) { writeFunction(s, it.value().first()); } } { AbstractMetaEnumList enums = meta_class->enums(); for (int i = 0; i < enums.size(); ++i) { const AbstractMetaEnum *enom = enums.at(i); if (shouldIgnoreEnum(enom)) continue; AbstractMetaEnumValueList values = enom->values(); QList indexes = uniqueEnumValueIndexes(values); for (int j = 0; j < indexes.size(); ++j) { AbstractMetaEnumValue *val = values.at(indexes.at(j)); s << "
    • " << val->name(); if (!val->stringValue().isEmpty()) s << " = " << val->stringValue(); s << "
      • " << endl; } s << "
    • " << enom->name() << "( value )
      • " << endl; FlagsTypeEntry *flags = enom->typeEntry()->flags(); if (flags) s << "
    • " << flags->flagsName() << "( value1, value2, ... )
      • " << endl; } } s << "
    " << endl; if (!nameToPrototypeFunctions.isEmpty()) { s << "

    Prototype Object Properties

    " << endl; if (meta_class->baseClass()) { s << "

    The " << meta_class->name() << " prototype object inherits properties from the " << "baseClass()) << "\">" << meta_class->baseClass()->name() << " prototype object and " << "also has the following properties.

    " << endl; } s << "
      " << endl; QMap::const_iterator it; for (it = nameToPrototypeFunctions.constBegin(); it != nameToPrototypeFunctions.constEnd(); ++it) { writeFunction(s, it.value().first()); } s << "
    " << endl; } if (!meta_class->isNamespace()) { s << "

    Instance Properties

    " << endl; { QList props = meta_class->propertySpecs(); if (!props.isEmpty()) { s << "

    " << meta_class->name() << " objects inherit properties from the " << meta_class->name() << " prototype object and also have the following properties.

    " << endl; s << "
      " << endl; for (int i = 0; i < props.size(); ++i) { s << "
    • " << props.at(i)->name() << "
      • " << endl; } s << "
    " << endl; } else { s << "

    " << meta_class->name() << " objects have no special properties beyond those " << "inherited from the " << meta_class->name() << " prototype object.

    " << endl; } } } writeDocumentFooter(s); }