diff options
author | Jerome Pasion <jerome.pasion@digia.com> | 2012-11-22 16:35:24 +0100 |
---|---|---|
committer | The Qt Project <gerrit-noreply@qt-project.org> | 2012-11-23 13:16:20 +0100 |
commit | 051aeb291646745559c47da160193bdcbd34ef2b (patch) | |
tree | 50040152b4dfe22238ef0446c9e57ff1b345bdd4 /examples/xmlpatterns/xquery/doc/src/globalVariables.qdoc | |
parent | b34af22fcc7e9321e5a7943763cd68a1d51a36d5 (diff) | |
download | qtxmlpatterns-051aeb291646745559c47da160193bdcbd34ef2b.tar.gz |
Doc: Modularized Qt XML Patterns documentation.
-moved snippets, images, documentation to src/xmlpatterns
-fixed \snippet tag
-ported module information from qtdoc repository
-enabled "make docs" for the module
-set up qdocconf file and .index file
-updated tests/auto/patternistexamples to point to the new
snippet locations
Change-Id: Ifd10733c277c6dbacac42898c8e7bacd00d23f27
Reviewed-by: Lars Knoll <lars.knoll@digia.com>
Diffstat (limited to 'examples/xmlpatterns/xquery/doc/src/globalVariables.qdoc')
-rw-r--r-- | examples/xmlpatterns/xquery/doc/src/globalVariables.qdoc | 201 |
1 files changed, 201 insertions, 0 deletions
diff --git a/examples/xmlpatterns/xquery/doc/src/globalVariables.qdoc b/examples/xmlpatterns/xquery/doc/src/globalVariables.qdoc new file mode 100644 index 0000000..08133f6 --- /dev/null +++ b/examples/xmlpatterns/xquery/doc/src/globalVariables.qdoc @@ -0,0 +1,201 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \example xmlpatterns/xquery/globalVariables + \title C++ Source Code Analyzer Example + + This example uses XQuery and the \c xmlpatterns command line utility to + query C++ source code. + + \tableofcontents + + \section1 Introduction + + Suppose we want to analyze C++ source code to find coding standard + violations and instances of bad or inefficient patterns. We can do + it using the common searching and pattern matching utilities to + process the C++ files (e.g., \c{grep}, \c{sed}, and \c{awk}). Now + we can also use XQuery with the Qt XML Patterns module. + + An extension to the \c{g++} open source C++ compiler + (\l{http://public.kitware.com/GCC_XML/HTML/Index.html} {GCC-XML}) + generates an XML description of C++ source code declarations. This + XML description can then be processed by Qt XML Patterns using + XQueries to navigate the XML description of the C++ source and + produce a report. Consider the problem of finding mutable global + variables: + + \section2 Reporting Uses of Mutable Global Variables + + Suppose we want to introduce threading to a C++ application that + was originally written without threading. In a threaded program, + mutable global variables can cause bugs, because one thread might + change a global variable that other threads are reading, or two + threads might try to set the same global variable. So when + converting our program to use threading, one of the things we must + do is protect the global variables to prevent the bugs described + above. How can we use XQuery and + \l{http://public.kitware.com/GCC_XML/HTML/Index.html} {GCC-XML} to + find the variables that need protecting? + + \section3 A C++ application + + Consider the declarations in this hypothetical C++ application: + + \snippet xmlpatterns/xquery/globalVariables/globals.cpp 0 + + \section3 The XML description of the C++ application + + Submitting this C++ source to + \l{http://public.kitware.com/GCC_XML/HTML/Index.html} {GCC-XML} + produces this XML description: + + \quotefromfile xmlpatterns/xquery/globalVariables/globals.gccxml + \printuntil + + \section3 The XQuery for finding global variables + + We need an XQuery to find the global variables in the XML + description. Here is our XQuery source. We walk through it in + \l{XQuery Code Walk-Through}. + + \quotefromfile xmlpatterns/xquery/globalVariables/reportGlobals.xq + \printuntil + + \section3 Running the XQuery + + To run the XQuery using the \c xmlpatterns command line utility, + enter the following command: + + \code + xmlpatterns reportGlobals.xq -param fileToOpen=globals.gccxml -output globals.html + \endcode + + \section3 The XQuery output + + The \c xmlpatterns command loads and parses \c globals.gccxml, + runs the XQuery \c reportGlobals.xq, and generates this report: + + \div {class="details"} + Start report: 2008-12-16T13:43:49.65Z + \enddiv + + Global variables with complex types: + \list 1 + \li \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14 + \li \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15 + \li \span {class="variableName"} {constComplex1} in globals.cpp at line 16 + \li \span {class="variableName"} {constComplex2} in globals.cpp at line 17 + \endlist + + Mutable global variables with primitives types: + \list 1 + \li \span {class="variableName"} {mutablePrimitive1} in globals.cpp at line 1 + \li \span {class="variableName"} {mutablePrimitive2} in globals.cpp at line 2 + \endlist + + \div {class="details"} End report: 2008-12-16T13:43:49.65Z \enddiv + + \section1 XQuery Code Walk-Through + + The XQuery source is in + \c{examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq} + It begins with two variable declarations that begin the XQuery: + + \quotefromfile xmlpatterns/xquery/globalVariables/reportGlobals.xq + \skipto declare variable + \printto (: + + The first variable, \c{$fileToOpen}, appears in the \c xmlpatterns + command shown earlier, as \c{-param fileToOpen=globals.gccxml}. + This binds the variable name to the file name. This variable is + then used in the declaration of the second variable, \c{$inDoc}, + as the parameter to the + \l{http://www.w3.org/TR/xpath-functions/#func-doc} {doc()} + function. The \c{doc()} function returns the document node of + \c{globals.gccxml}, which is assigned to \c{$inDoc} to be used + later in the XQuery as the root node of our searches for global + variables. + + Next skip to the end of the XQuery, where the \c{<html>} element + is constructed. The \c{<html>} will contain a \c{<head>} element + to specify a heading for the html page, followed by some style + instructions for displaying the text, and then the \c{<body>} + element. + + \quotefromfile xmlpatterns/xquery/globalVariables/reportGlobals.xq + \skipto <html xmlns + \printuntil + + The \c{<body>} element contains a call to the \c{local:report()} + function, which is where the query does the "heavy lifting." Note + the two \c{return} clauses separated by the \e {comma operator} + about halfway down: + + \quotefromfile xmlpatterns/xquery/globalVariables/reportGlobals.xq + \skipto declare function local:report() + \printuntil }; + + The \c{return} clauses are like two separate queries. The comma + operator separating them means that both \c{return} clauses are + executed and both return their results, or, rather, both output + their results. The first \c{return} clause searches for global + variables with complex types, and the second searches for mutable + global variables with primitive types. + + Here is the html generated for the \c{<body>} element. Compare + it with the XQuery code above: + + \quotefromfile xmlpatterns/xquery/globalVariables/globals.html + \skipto <body> + \printuntil </body> + + The XQuery declares three more local functions that are called in + turn by the \c{local:report()} function. \c{isComplexType()} + returns true if the variable has a complex type. The variable can + be mutable or const. + + \quotefromfile xmlpatterns/xquery/globalVariables/reportGlobals.xq + \skipto declare function local:isComplexType + \printuntil }; + + \c{isPrimitive()} returns true if the variable has a primitive + type. The variable must be mutable. + + \quotefromfile xmlpatterns/xquery/globalVariables/reportGlobals.xq + \skipto declare function local:isPrimitive + \printuntil }; + + \c{location()} returns a text constructed from the variable's file + and line number attributes. + + \quotefromfile xmlpatterns/xquery/globalVariables/reportGlobals.xq + \skipto declare function local:location + \printuntil }; + + */ |