Adding some documentation for Lighthouse

The spirit here is "something is better than nothing". Ie. its the first
itteration of documenting the classes. No general Lighthouse
introduction yet...

10 files changed, 393 insertions, 10 deletions

diff --git a/src/gui/kernel/qplatformglcontext_qpa.cpp b/src/gui/kernel/qplatformglcontext_qpa.cpp
index 5ed1d3d..a450b33 100644
--- a/src/gui/kernel/qplatformglcontext_qpa.cpp
+++ b/src/gui/kernel/qplatformglcontext_qpa.cpp
@@ -95,12 +95,18 @@ void QPlatformGLContextPrivate::setCurrentContext(QPlatformGLContext *context)
     threadContext->context = context;
 }
 
+/*!
+  Returns the platformWindow which this QPlatformGLContext belongs to.
+*/
 QPlatformWindow *QPlatformGLContext::platformWindow() const
 {
     Q_D(const QPlatformGLContext);
     return d->platformWindow;
 }
 
+/*!
+  Returns the last context which called makeCurrent. This function is thread aware.
+*/
 const QPlatformGLContext* QPlatformGLContext::currentContext()
 {
     QPlatformGLThreadContext *threadContext = qplatformgl_context_storage.localData();
@@ -110,11 +116,17 @@ const QPlatformGLContext* QPlatformGLContext::currentContext()
     return 0;
 }
 
+/*!
+    All subclasses needs to specify the platformWindow. It can be a null window.
+*/
 QPlatformGLContext::QPlatformGLContext(QPlatformWindow *platformWindow)
     :d_ptr(new QPlatformGLContextPrivate(platformWindow))
 {
 }
 
+/*!
+  If this is the current context for the thread, doneCurrent is called
+*/
 QPlatformGLContext::~QPlatformGLContext()
 {
     if (QPlatformGLContext::currentContext() == this) {
@@ -123,26 +135,45 @@ QPlatformGLContext::~QPlatformGLContext()
 
 }
 
+
+/*!
+    Makes it possible to set the context which can be the default for making new contexts.
+*/
 void QPlatformGLContext::setDefaultSharedContext(QPlatformGLContext *sharedContext)
 {
     QPlatformGLContextPrivate::staticSharedContext = sharedContext;
 }
 
+/*!
+    Default shared context is intended to be a globally awailable pointer to a context which can
+    be used for sharing resources when creating new contexts. Its default value is 0;
+*/
 const QPlatformGLContext *QPlatformGLContext::defaultSharedContext()
 {
     return QPlatformGLContextPrivate::staticSharedContext;
 }
 
+/*!
+    Reimplement in subclass to do makeCurrent on native GL context
+*/
 void QPlatformGLContext::makeCurrent()
 {
     QPlatformGLContextPrivate::setCurrentContext(this);
 }
 
+/*!
+    Reimplement in subclass to release current context.
+    Typically this is calling makeCurrent with 0 "surface"
+*/
 void QPlatformGLContext::doneCurrent()
 {
     QPlatformGLContextPrivate::setCurrentContext(0);
 }
 
+/*
+  internal: Needs to have a pointer to qGLContext. But since this is in QtGui we cant
+  have any type information.
+*/
 void *QPlatformGLContext::qGLContextHandle() const
 {
     Q_D(const QPlatformGLContext);
@@ -161,3 +192,42 @@ void QPlatformGLContext::deleteQGLContext()
     Q_D(QPlatformGLContext);
     d->qGLContextDeleteFunction(d->qGLContextHandle);
 }
+
+/*!
+    \class QPlatformGLContext
+    \since 4.8
+    \internal
+    \preliminary
+    \ingroup qpa
+
+    \brief The QPlatformGLContext class provides an abstraction for native GL contexts.
+
+    In QPA the way to support OpenGL or OpenVG or other technologies that requires a native GL
+    context is through the QPlatformGLContext wrapper.
+
+    There is no factory function for QPlatformGLContexts, but rather only one accessor function.
+    The only place to retrieve a QPlatformGLContext from is through a QPlatformWindow.
+
+    The context which is current for a specific thread can be collected by the currentContext()
+    function. This is how QPlatformGLContext also makes it possible to use the QtOpenGL module
+    withhout using QGLWidget. When using QGLContext::currentContext(), it will ask
+    QPlatformGLContext for the currentContext. Then a corresponding QGLContext will be returned,
+    which maps to the QPlatformGLContext.
+*/
+
+/*! \fn void swapBuffers()
+    Reimplement in subclass to native swap buffers calls
+*/
+
+/*! getProcAddress(const QString& procName)
+    Reimplement in subclass to native getProcAddr calls.
+
+    Note: its convenient to use qPrintable(const QString &str) to get the const char * pointer
+*/
+
+/*! platformWindowFormat() const
+    QWidget has the function qplatformWindowFormat(). That function is for the application
+    programmer to request the format of the window and the context that he wants.
+
+    Reimplement this function in a subclass to indicate what format the glContext actually has.
+*/
diff --git a/src/gui/kernel/qplatformintegration_qpa.cpp b/src/gui/kernel/qplatformintegration_qpa.cpp
index e2a493d..2a9bf77 100644
--- a/src/gui/kernel/qplatformintegration_qpa.cpp
+++ b/src/gui/kernel/qplatformintegration_qpa.cpp
@@ -55,16 +55,35 @@ QPixmap QPlatformIntegration::grabWindow(WId window, int x, int y, int width, in
     return QPixmap();
 }
 
+/*!
+    Factory function for the eventloop integration interface.
+
+    Default implementation returns 0, which causes the eventloop to run in a single thread mode.
+
+    \sa QPlatformEventLoopIntegration
+*/
 QPlatformEventLoopIntegration *QPlatformIntegration::createEventLoopIntegration() const
 {
     return 0;
 }
 
+/*!
+    Returns wheter the given platform integration supports OpenGL.
+
+    Default implementation returns false,
+*/
 bool QPlatformIntegration::hasOpenGL() const
 {
     return false;
 }
 
+/*!
+    Accessor for the platform integrations fontdatabase.
+
+    Default implementation returns a default QPlatformFontDatabase.
+
+    \sa QPlatformFontDatabase
+*/
 QPlatformFontDatabase *QPlatformIntegration::fontDatabase() const
 {
     static QPlatformFontDatabase *db = 0;
@@ -74,4 +93,104 @@ QPlatformFontDatabase *QPlatformIntegration::fontDatabase() const
     return db;
 }
 
+/*!
+    \class QPlatformIntegration
+    \since 4.8
+    \internal
+    \preliminary
+    \ingroup qpa
+    \brief The QPlatformIntegration class is the entry for WindowSystem specific functionality.
+
+    QPlatformIntegration is the single entry point for windowsystem specific functionality when
+    using the QPA platform. It has factory functions for creating platform specific pixmaps and
+    windows. The class also controlls the font subsystem.
+
+    QPlatformIntegration is a singelton class which gets instansiated in the QApplication
+    constructor. The QPlatformIntegration instance do not have ownership of objects it creates in
+    functions where the name starts with create. However, functions which don't have a name
+    starting with create acts as assessors to member variables.
+
+    It is not trivial to create or build a platform plugin outside of the Qt source tree. Therefor
+    the recommended approach for making new platform plugin is to copy an existing plugin inside
+    the QTSRCTREE/src/plugins/platform and develop the plugin inside the source tree.
+
+    The minimal platformintegration is the smallest platform integration it is possible to make,
+    which makes it an ideal starting point for new plugins. For a slightly more advanced plugin,
+    consider reviewing the directfb plugin, or the testlite plugin.
+*/
+
+/*!
+    \fn QPixmapData *createPixmapData(QPixmapData::PixelType type) const
+
+    Factory function for QPixmapData. PixelType can be either PixmapType or BitmapType.
+    \sa QPixmapData
+*/
+
+/*!
+    \fn QPlatformWindow *createPlatformWindow(QWidget *widget, WId winId = 0) const
+
+    Factory function for QPlatformWindow. The widget parameter is a pointer to the top level
+    widget(tlw) which the QPlatformWindow is suppose to be created for. The WId handle is actually
+    never used, but there for future reference. Its purpose is if it is going to be possible to
+    create QPlatformWindows on existing WId.
+
+    All tlw has to have a QPlatformWindow, and it will be created when the QPlatformWindow is set
+    to be visible for the first time. If the tlw's window flags are changed, or if the tlw's
+    QPlatformWindowFormat is changed, then the tlw's QPlatformWindow is deleted and a new one is
+    created.
+
+    \sa QPlatformWindow, QPlatformWindowFormat
+    \sa createWindowSurface(QWidget *widget, WId winId) const
+*/
+
+/*!
+    \fn QWindowSurface *createWindowSurface(QWidget *widget, WId winId) const
+
+    Factory function for QWindowSurface. The QWidget parameter is a pointer to the
+    top level widget(tlw) the window surface is created for. A QPlatformWindow is allways created
+    before the QWindowSurface for tlw where the widget also requires a WindowSurface. It is
+    possible to create top level QWidgets without a QWindowSurface by specifying
+    QPlatformWindowFormat::setWindowSurface(false) for the tlw QPlatformWindowFormat.
+
+    \sa QWindowSurface
+    \sa createPlatformWindow(QWidget *widget, WId winId = 0) const
+*/
+
+/*!
+    \fn void moveToScreen(QWidget *window, int screen)
+
+    This function is called when a QWidget is displayed on screen, or the QWidget is to be
+    displayed on a new screen. The QWidget parameter is a pointer to the top level widget and
+    the int parameter is the index to the screen in QList<QPlatformScreen *> screens() const.
+
+    Default implementation does nothing.
+
+    \sa screens() const
+*/
+
+/*!
+    \fn QList<QPlatformScreen *> screens() const
+
+    Accessor function to a list of all the screens on the current system. The screen with the
+    index == 0 is the default/main screen.
+*/
+
+/*!
+    \fn bool isVirtualDesktop()
+
+    Returns if the current windowing system configuration defines all the screens to be one
+    desktop(virtual desktop), or if each screen is a desktop of its own.
+
+    Default implementation returns false.
+*/
+
+/*!
+    \fn QPixmap grabWindow(WId window, int x, int y, int width, int height) const
+
+    This function is called when Qt needs to be able to grab the content of a window.
+
+    Returnes the content of the window specified with the WId handle within the boundaries of
+    QRect(x,y,width,height).
+*/
+
 QT_END_NAMESPACE
diff --git a/src/gui/kernel/qplatformintegration_qpa.h b/src/gui/kernel/qplatformintegration_qpa.h
index b1f4e5f..f01b4f4 100644
--- a/src/gui/kernel/qplatformintegration_qpa.h
+++ b/src/gui/kernel/qplatformintegration_qpa.h
@@ -69,10 +69,10 @@ public:
     virtual QPixmapData *createPixmapData(QPixmapData::PixelType type) const = 0;
     virtual QPlatformWindow *createPlatformWindow(QWidget *widget, WId winId = 0) const = 0;
     virtual QWindowSurface *createWindowSurface(QWidget *widget, WId winId) const = 0;
-    virtual void moveToScreen(QWidget *window, int screen) {Q_UNUSED(window); Q_UNUSED(screen);}
 
 // Window System functions
     virtual QList<QPlatformScreen *> screens() const = 0;
+    virtual void moveToScreen(QWidget *window, int screen) {Q_UNUSED(window); Q_UNUSED(screen);}
     virtual bool isVirtualDesktop() { return false; }
     virtual QPixmap grabWindow(WId window, int x, int y, int width, int height) const;
 
diff --git a/src/gui/kernel/qplatformscreen_qpa.cpp b/src/gui/kernel/qplatformscreen_qpa.cpp
index 478d2d6..5e80ba8 100644
--- a/src/gui/kernel/qplatformscreen_qpa.cpp
+++ b/src/gui/kernel/qplatformscreen_qpa.cpp
@@ -43,6 +43,12 @@
 #include <QtGui/qapplication.h>
 #include <QtGui/qdesktopwidget.h>
 
+/*!
+    Return the given top level widget for a given position.
+
+    Default implementation retrieves a list of all top level widgets and finds the first widget
+    which contains point \a pos
+*/
 QWidget *QPlatformScreen::topLevelAt(const QPoint & pos) const
 {
     QWidgetList list = QApplication::topLevelWidgets();
@@ -56,6 +62,13 @@ QWidget *QPlatformScreen::topLevelAt(const QPoint & pos) const
     return 0;
 }
 
+/*! \fn physicalSize() const
+    Reimplement in subclass to return the physical size of the screen. This function is used by
+    QFont to convert point sizes to pixel sizes.
+
+    Default implementation takes the pixel size of the screen, considers a dpi of 100 and returns
+    the calculated (and probably wrong) physical size
+*/
 QSize QPlatformScreen::physicalSize() const
 {
     static const int dpi = 100;
@@ -64,3 +77,38 @@ QSize QPlatformScreen::physicalSize() const
     return QSize(width,height);
 }
 
+/*!
+    \class QPlatformScreen
+    \since 4.8
+    \internal
+    \preliminary
+    \ingroup qpa
+
+    \brief The QPlatformScreen class provides an abstraction for visual displays.
+
+    Many window systems has support for retrieving information on the attached displays. To be able
+    to query the display QPA uses QPlatformScreen. Qt its self is most dependent on the
+    physicalSize() function, since this is the function it uses to calculate the dpi to use when
+    converting point sizes to pixels sizes. However, this is unfortunate on some systems, as the
+    native system fakes its dpi size.
+
+    QPlatformScreen is also used by the public api QDesktopWidget for information about the desktop.
+ */
+
+/*! \fn geometry() const
+    Reimplement in subclass to return the pixel geometry of the screen
+*/
+
+/*! \fn availableGeometry() const
+    Reimplement in subclass to return the pixel geometry of the available space
+    This normally is the desktop screen minus the task manager, global menubar etc.
+*/
+
+/*! \fn depth() const
+    Reimplement in subclass to return current depth of the screen
+*/
+
+/*! \fn format() const
+    Reimplement in subclass to return the image format which corresponds to the screen format
+*/
+
diff --git a/src/gui/kernel/qplatformscreen_qpa.h b/src/gui/kernel/qplatformscreen_qpa.h
index 1704f0f..9080489 100644
--- a/src/gui/kernel/qplatformscreen_qpa.h
+++ b/src/gui/kernel/qplatformscreen_qpa.h
@@ -70,6 +70,7 @@ public:
     virtual int depth() const = 0;
     virtual QImage::Format format() const = 0;
     virtual QSize physicalSize() const;
+    //jl: should setDirty be removed.
     virtual void setDirty(const QRect &) {}
     virtual QWidget *topLevelAt(const QPoint &point) const;
 };
diff --git a/src/gui/kernel/qplatformwindow_qpa.cpp b/src/gui/kernel/qplatformwindow_qpa.cpp
index 9d722d8..378fc68 100644
--- a/src/gui/kernel/qplatformwindow_qpa.cpp
+++ b/src/gui/kernel/qplatformwindow_qpa.cpp
@@ -51,6 +51,10 @@ class QPlatformWindowPrivate
     friend class QPlatformWindow;
 };
 
+/*!
+    Constructs a platform window with the given top level widget.
+*/
+
 QPlatformWindow::QPlatformWindow(QWidget *tlw)
     : d_ptr(new QPlatformWindowPrivate)
 {
@@ -59,22 +63,37 @@ QPlatformWindow::QPlatformWindow(QWidget *tlw)
     tlw->setPlatformWindow(this);
 }
 
+/*!
+    Virtual destructor does not delete its top level widget.
+*/
 QPlatformWindow::~QPlatformWindow()
 {
 }
 
+/*!
+    Returnes the widget which belongs to the QPlatformWindow
+*/
 QWidget *QPlatformWindow::widget() const
 {
     Q_D(const QPlatformWindow);
     return d->tlw;
 }
 
+/*!
+    This function is called by Qt whenever a window is moved or the window is resized. The resize
+    can happen programatically(from ie. user application) or by the window manager. This means that
+    there is no need to call this function specifically from the window manager callback, instead
+    call QWindowSystemInterface::handleGeometryChange(QWidget *w, const QRect &newRect);
+*/
 void QPlatformWindow::setGeometry(const QRect &rect)
 {
     Q_D(QPlatformWindow);
     d->rect = rect;
 }
 
+/*!
+    Returnes the current geometry of a window
+*/
 QRect QPlatformWindow::geometry() const
 {
     Q_D(const QPlatformWindow);
@@ -82,14 +101,16 @@ QRect QPlatformWindow::geometry() const
 }
 
 /*!
-Reimplemented in subclasses to show the surface if \a visible is \c true, and hide it if \a visible is \c false.
+    Reimplemented in subclasses to show the surface
+    if \a visible is \c true, and hide it if \a visible is \c false.
 */
 void QPlatformWindow::setVisible(bool visible)
 {
     Q_UNUSED(visible);
 }
 /*!
-Requests setting the window flags of this surface to \a type. Returns the actual flags set.
+    Requests setting the window flags of this surface
+    to \a type. Returns the actual flags set.
 */
 Qt::WindowFlags QPlatformWindow::setWindowFlags(Qt::WindowFlags flags)
 {
@@ -107,23 +128,83 @@ Qt::WindowFlags QPlatformWindow::windowFlags() const
     return d->flags;
 }
 
+/*!
+  Reimplement in subclasses to return a handle to the native window
+*/
 WId QPlatformWindow::winId() const { return WId(0); }
 
-void QPlatformWindow::setParent(const QPlatformWindow *) { qWarning("This plugin does not support setParent!"); }
+/*!
+    This function is called to enable native child widgets in QPA. It is common not to support this
+    feature in Window systems, but can be faked. When this function is called all geometry of this
+    platform window will be relative to the parent.
+*/
+//jl: It would be usefull to have a property on the platform window which indicated if the sub-class
+// supported the setParent. If not, then geometry would be in screen coordinates.
+void QPlatformWindow::setParent(const QPlatformWindow *parent)
+{
+    Q_UNUSED(parent);
+    qWarning("This plugin does not support setParent!");
+}
 
-void QPlatformWindow::setWindowTitle(const QString &) {}
+/*!
+  Reimplement to set the window title to \a title
+*/
+void QPlatformWindow::setWindowTitle(const QString &title) {}
 
+/*!
+  Reimplement to be able to let Qt rais windows to the top of the desktop
+*/
 void QPlatformWindow::raise() { qWarning("This plugin does not support raise()"); }
 
+/*!
+  Reimplement to be able to let Qt lower winows to the bottom of the dekstop
+*/
 void QPlatformWindow::lower() { qWarning("This plugin does not support lower()"); }
 
+/*!
+  Reimplement to be able to let Qt set the opacity level of a window
+*/
 void QPlatformWindow::setOpacity(qreal level)
 {
     Q_UNUSED(level);
     qWarning("This plugin does not support setting window opacity");
 }
 
+/*!
+  Reimplement to return the glContext assosiated with the window.
+*/
 QPlatformGLContext *QPlatformWindow::glContext() const
 {
     return 0;
 }
+
+/*!
+    \class QPlatformWindow
+    \since 4.8
+    \internal
+    \preliminary
+    \ingroup qpa
+
+    \brief The QPlatformWindow class provides an abstraction for top-level windows.
+
+    The QPlatformWindow abstraction is used by QWidget for all its top level widgets. It is being
+    created by calling the createPlatformWindow function in the loaded QPlatformIntegration
+    instance.
+
+    QPlatformWindow is used to signal to the windowing system, how Qt persieves its frame.
+    However, it is not concerned with how Qt renders into the window it represents.
+
+    Top level QWidgets(tlw) will allways have a QPlatformWindow. However, it is not neccesary for
+    all tlw to have a QWindowSurface. This is the case for QGLWidget. And could be the case for
+    widgets where some  3.party renders into it.
+
+    The platform specific window handle can be retrieved by the winId function.
+
+    QPlatformWindow is also the way QPA defines how native child windows should be supported
+    through the setParent function.
+
+    The only way to retrieve a QPlatformGLContext in QPA is by calling the glContext() function
+    on QPlatformWindow.
+
+    \sa QWindowSurface, QWidget
+*/
diff --git a/src/gui/kernel/qplatformwindow_qpa.h b/src/gui/kernel/qplatformwindow_qpa.h
index 6dfba05..90bc1cb 100644
--- a/src/gui/kernel/qplatformwindow_qpa.h
+++ b/src/gui/kernel/qplatformwindow_qpa.h
@@ -75,7 +75,7 @@ public:
     virtual WId winId() const;
     virtual void setParent(const QPlatformWindow *window);
 
-    virtual void setWindowTitle(const QString &);
+    virtual void setWindowTitle(const QString &title);
     virtual void raise();
     virtual void lower();
 
diff --git a/src/gui/kernel/qplatformwindowformat_qpa.cpp b/src/gui/kernel/qplatformwindowformat_qpa.cpp
index f0dad17..ade6bb3 100644
--- a/src/gui/kernel/qplatformwindowformat_qpa.cpp
+++ b/src/gui/kernel/qplatformwindowformat_qpa.cpp
@@ -102,9 +102,15 @@ public:
 /*!
     \class QPlatformWindowFormat
     \brief The QPlatformWindowFormat class specifies the display format of an OpenGL
-    rendering context.
+    rendering context and if possible attributes of the corresponding QPlatformWindow.
 
-    \ingroup painting-3D
+    \ingroup painting
+
+    QWidget has a setter and getter function for QPlatformWindowFormat. These functions can be used
+    by the application programmer to signal what kind of format he wants to the window and glcontext
+    should have. However, it is not allways possible to furfill these requirements. The application
+    programmer should therefor check the resulting QPlatformWindowFormat from QPlatformGLContext
+    to see the format that was actually created.
 
     A display format has several characteristics:
     \list
@@ -162,7 +168,7 @@ public:
         United States and other countries.
     \endlegalese
 
-    \sa QGLContext, QGLWidget
+    \sa QPlatformContext, QWidget
 */
 
 /*!
diff --git a/src/gui/painting/qwindowsurface.cpp b/src/gui/painting/qwindowsurface.cpp
index e9eb9c5..3ee8281 100644
--- a/src/gui/painting/qwindowsurface.cpp
+++ b/src/gui/painting/qwindowsurface.cpp
@@ -74,7 +74,7 @@ public:
     \since 4.3
     \internal
     \preliminary
-    \ingroup qws
+    \ingroup qws qpa
 
     \brief The QWindowSurface class provides the drawing area for top-level
     windows.
@@ -179,11 +179,20 @@ QRect QWindowSurface::geometry() const
     return d_ptr->geometry;
 }
 #else
+
+/*!
+      Sets the size of the windowsurface to be \a size.
+
+      \sa size()
+*/
 void QWindowSurface::resize(const QSize &size)
 {
     d_ptr->size = size;
 }
 
+/*!
+    Returns the current size of the windowsurface.
+*/
 QSize QWindowSurface::size() const
 {
     return d_ptr->size;
diff --git a/src/gui/text/qplatformfontdatabase_qpa.cpp b/src/gui/text/qplatformfontdatabase_qpa.cpp
index 7a89fe4..d6dff41 100644
--- a/src/gui/text/qplatformfontdatabase_qpa.cpp
+++ b/src/gui/text/qplatformfontdatabase_qpa.cpp
@@ -165,6 +165,23 @@ bool QSupportedWritingSystems::supported(QFontDatabase::WritingSystem writingSys
     return d->vector.at(writingSystem);
 }
 
+/*!
+    \class QSupportedWritingSystems
+    \brief The QSupportedWritingSystems class is used when registering fonts with the internal Qt
+    fontdatabase
+    \ingroup painting
+
+    Its to provide an easy to use interface for indicating what writing systems a specific font
+    supports.
+
+*/
+
+/*!
+  This function is called once at startup by Qts internal fontdatabase. Reimplement this function
+  in a subclass for a convenient place to initialise the internal fontdatabase.
+
+  The default implementation looks in the fontDir() location and registers all qpf2 fonts.
+*/
 void QPlatformFontDatabase::populateFontDatabase()
 {
     QString fontpath = fontDir();
@@ -188,6 +205,9 @@ void QPlatformFontDatabase::populateFontDatabase()
     }
 }
 
+/*!
+
+*/
 QFontEngine *QPlatformFontDatabase::fontEngine(const QFontDef &fontDef, QUnicodeTables::Script script, void *handle)
 {
     Q_UNUSED(script);
@@ -198,6 +218,9 @@ QFontEngine *QPlatformFontDatabase::fontEngine(const QFontDef &fontDef, QUnicode
     return engine;
 }
 
+/*!
+
+*/
 QStringList QPlatformFontDatabase::fallbacksForFamily(const QString family, const QFont::Style &style, const QUnicodeTables::Script &script) const
 {
     Q_UNUSED(family);
@@ -219,12 +242,18 @@ QStringList QPlatformFontDatabase::addApplicationFont(const QByteArray &fontData
     return QStringList();
 }
 
+/*!
+
+*/
 void QPlatformFontDatabase::releaseHandle(void *handle)
 {
     QByteArray *fileDataPtr = static_cast<QByteArray *>(handle);
     delete fileDataPtr;
 }
 
+/*!
+
+*/
 QString QPlatformFontDatabase::fontDir() const
 {
     QString fontpath = QString::fromLocal8Bit(qgetenv("QT_QPA_FONTDIR"));
@@ -238,4 +267,24 @@ QString QPlatformFontDatabase::fontDir() const
     return fontpath;
 }
 
+/*!
+    \class QPlatformFontDatabase
+    \brief The QPlatformFontDatabase makes it possible to customize how fonts are picked up, and
+    and how they are rendered
+
+    \ingroup painting
+
+    QPlatformFontDatabase is the superclass which is intended to let platform implementations use
+    native font handling.
+
+    Qt has its internal fontdatabase which it uses to pick up available fonts. To be able
+    to populate this database subclass this class, and reimplement populateFontDatabase().
+
+    Use the function registerFont to populate the internal fontdatabase.
+
+    Sometimes a specified font does not have the required glyphs, then the fallbackForFamily
+    function is called.
+
+    \sa QSupportedWritingSystems
+*/
 QT_END_NAMESPACE