Doc: Added documentation for dumpcpp and dumpdoc tools

Moved from the qtdoc repo

Change-Id: I05a84e0e3f4d2b08a1712da3cf8d9515e9987b74
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>

6 files changed, 266 insertions, 1 deletions

diff --git a/examples/activeqt/webbrowser/doc/images/activeqt-webbrowser-example.png b/examples/activeqt/webbrowser/doc/images/activeqt-webbrowser-example.png
new file mode 100644
index 0000000..4913594
--- /dev/null
+++ b/examples/activeqt/webbrowser/doc/images/activeqt-webbrowser-example.png
diff --git a/examples/activeqt/webbrowser/doc/src/webbrowser.qdoc b/examples/activeqt/webbrowser/doc/src/webbrowser.qdoc
index 7d79928..a3fd6ca 100644
--- a/examples/activeqt/webbrowser/doc/src/webbrowser.qdoc
+++ b/examples/activeqt/webbrowser/doc/src/webbrowser.qdoc
@@ -34,6 +34,8 @@
     application. The user interface has been developed using the Qt
     Designer integration of the QAxWidget class.
 
+    \image activeqt-webbrowser-example.png
+
     The code demonstrates how the Qt application can communicate
     with the embedded ActiveX controls using signals, slots and the
     dynamicCall() function.
diff --git a/src/activeqt/doc/snippets/doc_src_activeqt-dumpcpp.cpp b/src/activeqt/doc/snippets/doc_src_activeqt-dumpcpp.cpp
new file mode 100644
index 0000000..b2595d5
--- /dev/null
+++ b/src/activeqt/doc/snippets/doc_src_activeqt-dumpcpp.cpp
@@ -0,0 +1,65 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
+**     of its contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [0]
+Outlook::Application *outlook = new Outlook::Application;
+//! [0]
+
+
+//! [1]
+Outlook::_NameSpace *session = outlook->Session();
+//! [1]
+
+
+//! [2]
+Outlook::NameSpace *session = outlook->Session();
+//! [2]
+
+
+//! [3]
+Outlook::_NameSpace *tmp = outlook->Session();
+Outlook::NameSpace *session = new Outlook::NameSpace(tmp);
+delete tmp; // or any other use of tmp: segfault
+//! [3]
+
+
+//! [4]
+Outlook::NameSpace *session = new Outlook::NameSpace(outlook->Session());
+//! [4]
diff --git a/src/activeqt/doc/src/activeqt-dumpcpp.qdoc b/src/activeqt/doc/src/activeqt-dumpcpp.qdoc
new file mode 100644
index 0000000..34cee4c
--- /dev/null
+++ b/src/activeqt/doc/src/activeqt-dumpcpp.qdoc
@@ -0,0 +1,129 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** 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 Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page activeqt-dumpcpp.html
+    \title The dumpcpp Tool (ActiveQt)
+
+    \ingroup activeqt-tools
+
+    \keyword dumpcpp
+
+    The \c dumpcpp tool generates a C++ namespace for a type library.
+
+    To generate a C++ namespace for a type library, call \c dumpcpp with the
+    following command-line parameters:
+
+    \table
+    \header
+    \li Option
+    \li Result
+    \row
+    \li input
+    \li Generate documentation for \e input. \e input can specify a type library file or a type
+    library ID, or a CLSID or ProgID for an object
+    \row
+    \li -o file
+    \li Writes the class declaration to \e {file}.h and meta object infomation to \e {file}.cpp
+    \row
+    \li -n namespace
+    \li Generate a C++ namespace \e namespace
+    \row
+    \li -nometaobject
+    \li Do not generate a .cpp file with the meta object information.
+    The meta object is then generated in runtime.
+    \row
+    \li -getfile libid
+    \li Print the filename for the typelibrary \e libid to stdout
+    \row
+    \li -compat
+    \li Generate namespace with dynamicCall-compatible API
+    \row
+    \li -v
+    \li Print version information
+    \row
+    \li -h
+    \li Print help
+    \endtable
+
+    \c dumpcpp can be integrated into the \c qmake build system. In your .pro
+    file, list the type libraries you want to use in the TYPELIBS variable:
+
+    \snippet activeqt/qutlook/qutlook.pro 0
+
+    The generated namespace will declare all enumerations, as well as one QAxObject subclass
+    for each \c coclass and \c interface declared in the type library. coclasses marked with
+    the \c control attribute will be wrapped by a QAxWidget subclass.
+
+    Those classes that wrap creatable coclasses  (i.e. coclasses that are not marked
+    as \c noncreatable) have a default constructor; this is typically a single class
+    of type \c Application.
+
+    \snippet doc_src_activeqt-dumpcpp.cpp 0
+
+    All other classes can only be created by passing an IDispatch interface pointer
+    to the constructor; those classes should however not be created explicitly.
+    Instead, use the appropriate API of already created objects.
+
+    \snippet doc_src_activeqt-dumpcpp.cpp 1
+
+    All coclass wrappers also have one constructors taking an interface wrapper class
+    for each interface implemented.
+
+    \snippet doc_src_activeqt-dumpcpp.cpp 2
+
+    You have to create coclasses to be able to connect to signals of the subobject.
+    Note that the constructor deletes the interface object, so the following will
+    cause a segmentation fault:
+
+    \snippet doc_src_activeqt-dumpcpp.cpp 3
+
+    If the return type is of a coclass or interface type declared in another
+    type library you have to include the namespace header for that other type
+    library before including the header for the namespace you want to use
+    (both header have to be generated with this tool).
+
+    By default, methods and property returning subobjects will use the type as in
+    the type library. The caller of the function is responsible for deleting or
+    reparenting the object returned. If the \c -compat switch is set, properties
+    and method returning a COM object have the return type \c IDispatch*, and
+    the namespace will not declare wrapper classes for interfaces.
+
+    In this case, create the correct wrapper class explicitly:
+
+    \snippet doc_src_activeqt-dumpcpp.cpp 4
+
+    You can of course use the IDispatch* returned directly, in which case you have to
+    call \c Release() when finished with the interface.
+
+    All classes in the namespace are tagged with a macro that allows you to export
+    or import them from a DLL. To do that, declare the macro to expand to
+    \c __declspec(dllimport/export) before including the header file.
+
+    To build the tool you must first build the QAxContainer library.
+    Then run your make tool in \c tools/dumpcpp.
+*/
diff --git a/src/activeqt/doc/src/activeqt-dumpdoc.qdoc b/src/activeqt/doc/src/activeqt-dumpdoc.qdoc
new file mode 100644
index 0000000..7005542
--- /dev/null
+++ b/src/activeqt/doc/src/activeqt-dumpdoc.qdoc
@@ -0,0 +1,69 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** 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 Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page activeqt-dumpdoc.html
+    \title The dumpdoc Tool (ActiveQt)
+
+    \ingroup activeqt-tools
+
+    \keyword dumpdoc
+
+    The \c dumpdoc tool generates Qt-style documentation for any
+    COM object and writes it into the file specified.
+
+    Call \c dumpdoc with the following command line parameters:
+
+    \table
+    \header
+    \li Option
+    \li Result
+    \row
+    \li -o file
+    \li Writes output to \e file
+    \row
+    \li object
+    \li Generate documentation for \e object
+    \row
+    \li -v
+    \li Print version information
+    \row
+    \li -h
+    \li Print help
+    \endtable
+
+    \e object must be an object installed on the local machine (ie.
+    remote objects are not supported), and can include subobjects
+    accessible through properties, ie.
+    \c Outlook.Application/Session/CurrentUser
+
+    The generated file will be an HTML file using Qt documentation
+    style.
+
+    To build the tool you must first build the QAxContainer library.
+    Then run your make tool in \c tools/dumpdoc.
+*/
diff --git a/src/activeqt/doc/src/activeqt-index.qdoc b/src/activeqt/doc/src/activeqt-index.qdoc
index 70f65d5..65ba218 100644
--- a/src/activeqt/doc/src/activeqt-index.qdoc
+++ b/src/activeqt/doc/src/activeqt-index.qdoc
@@ -30,7 +30,7 @@
     \title Tools for ActiveQt
     \brief Tools to help integrate Qt applications with ActiveX components.
 
-    These tools provide support for integrating Qt with ActiveX components.
+    The following tools enable Qt integration with the ActiveX components.
 
     \sa {ActiveQt Framework}
 */