Document JavaScript extensions.

Change-Id: I093f753285af2e9a9d6f3b521e23f8c24b8ac3cf
Reviewed-by: Joerg Bornemann <joerg.bornemann@digia.com>

5 files changed, 439 insertions, 1 deletions

diff --git a/doc/reference/jsextensions/jsextension-file.qdoc b/doc/reference/jsextensions/jsextension-file.qdoc
new file mode 100644
index 000000000..5fe0e10dd
--- /dev/null
+++ b/doc/reference/jsextensions/jsextension-file.qdoc
@@ -0,0 +1,72 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the Qt Build Suite.
+**
+** 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.
+**
+****************************************************************************/
+
+/*!
+    \contentspage index.html
+    \page jsextension-file.html
+    \ingroup list-of-builtin-services
+
+    \title The File Service
+    \brief Provides files system operations.
+
+    The \c File service offers limited access to the file system for operations such as copying
+    or removing files.
+
+    \section1 Making the service available
+    In order to gain access to these operations, you need to import the service using the
+    following statement at the top of your project file:
+    \code
+    import qbs.File
+    \endcode
+
+    \section1 Available operations
+
+    \section2 copy
+    \code
+    File.copy(sourceFilePath, targetFilePath)
+    \endcode
+    Copies \c sourceFilePath to \c targetFilePath. Any directory components in \c targetFilePath
+    that do not yet exist will be created. If \c sourceFilePath is a directory, a recursive
+    copy will be made. If an error happens, a JavaScript exception will be thrown.
+    \note \c targetFilePath must be the counterpart of \c sourceFilePath at the new location,
+    \b{not} the new parent directory. This allows the copy to have a different name and is true
+    even if \c sourceFilePath is a directory.
+
+    \section2 exists
+    \code
+    File.exists(filePath)
+    \endcode
+    Returns true if and only if there is a file at \c filePath.
+
+    \section2 remove
+    \code
+    File.remove(filePath)
+    \endcode
+    Removes the file at \c filePath. In case of a directory, it will be removed recursively.
+*/
diff --git a/doc/reference/jsextensions/jsextension-fileinfo.qdoc b/doc/reference/jsextensions/jsextension-fileinfo.qdoc
new file mode 100644
index 000000000..76237f5aa
--- /dev/null
+++ b/doc/reference/jsextensions/jsextension-fileinfo.qdoc
@@ -0,0 +1,110 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the Qt Build Suite.
+**
+** 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.
+**
+****************************************************************************/
+
+/*!
+    \contentspage index.html
+    \page jsextension-fileinfo.html
+    \ingroup list-of-builtin-services
+
+    \title The FileInfo Service
+    \brief Provides operations on file paths.
+
+    The \c FileInfo service offers various operations on file paths such as turning absolute
+    paths into relative ones, splitting a path into its components and so on.
+
+    \section1 Making the service available
+
+    In order to gain access to these operations, you need to import the service using the
+    following statement at the top of your project file:
+    \code
+    import qbs.FileInfo
+    \endcode
+
+    \section1 Available operations
+
+    \section2 baseName
+    \code
+    FileInfo.baseName(filePath)
+    \endcode
+    Returns the file name of \c filePath up to (but not including) the first '.' character.
+
+    \section2 completeBaseName
+    \code
+    FileInfo.completeBaseName(filePath)
+    \endcode
+    Returns the file name of \c filePath up to (but not including) the last '.' character.
+
+    \section2 fileName
+    \code
+    FileInfo.fileName(filePath)
+    \endcode
+    Returns the last component of \c filePath, i.e. everything after the last '/' character.
+
+    \section2 fromWindowsSeparator
+    \code
+    FileInfo.fromWindowsSeparator(filePath)
+    \endcode
+    Returns \c filePath with all '\\' characters replaced by '/'.
+
+    \section2 isAbsolutePath
+    \code
+    FileInfo.isAbsolutPath(filePath)
+    \endcode
+    Returns true if \c filePath is an absolute path and false if it is a relative one.
+
+    \section2 joinPaths
+    \code
+    FileInfo.joinPaths(path1, path2, ...)
+    \endcode
+    Concatenates the given paths using the '/' character.
+
+    \section2 path
+    \code
+    FileInfo.path(filePath)
+    \endcode
+    Returns the part of \c filePath that is not the file name, i.e. everything up to
+    (but not including) the last '/' character. If \c filePath is just a file name, then '.'
+    is returned. If \c filePath ends with a '/' character, then the file name is assumed to be empty
+    for the purpose of the above definition.
+
+    \section2 relativePath
+    \code
+    FileInfo.relativePath(dirPath, filePath)
+    \endcode
+    Returns a relative path so that joining \c dirPath and the returned path results in \c filePath.
+    If necessary, '..' components are inserted.
+    The function assumes \c dirPath and \c filePath to be absolute paths and \c dirPath to
+    be a directory.
+
+    \section2 toWindowsSeparator
+    \code
+    FileInfo.toWindowsSeparator(filePath)
+    \endcode
+    Returns \c filePath with all '/' characters replaced by '\\'.
+*/
diff --git a/doc/reference/jsextensions/jsextension-process.qdoc b/doc/reference/jsextensions/jsextension-process.qdoc
new file mode 100644
index 000000000..65d96d1aa
--- /dev/null
+++ b/doc/reference/jsextensions/jsextension-process.qdoc
@@ -0,0 +1,140 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the Qt Build Suite.
+**
+** 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.
+**
+****************************************************************************/
+
+/*!
+    \contentspage index.html
+    \page jsextension-process.html
+    \ingroup list-of-builtin-services
+
+    \title The Process Service
+    \brief Allows to start external processes.
+
+    The \c Process service allows you to start processes, track their output and so on.
+
+    \section1 Making the service available
+    In order to gain access to these operations, you need to import the service using the
+    following statement at the top of your project file:
+    \code
+    import qbs.Process
+    \endcode
+
+    \section1 Available operations
+
+    \section2 Constructor
+    \code
+    Process()
+    \endcode
+    Allocates and returns a new Process object.
+
+    \section2 close
+    \code
+    close()
+    \endcode
+    Frees the resources associated with the process. We recommended to always call this function as
+    soon as you are finished with the process.
+
+    \section2 exec
+    \code
+    exec(filePath, arguments, throwOnError)
+    \endcode
+    Executes the program at \c filePath with the given argument list and blocks until the
+    process is finished. If an error occors (e.g. there is no executable file at \c filePath)
+    and \c throwOnError is true, then a JavaScript exception will be thrown. Otherwise
+    (the default), -1 will be returned in case of an error. The normal return code is the exit code
+    of the process.
+
+    \section2 exitCode
+    \code
+    exitCode()
+    \endcode
+    Returns the exit code of the process. This is needed for retrieving the exit code from
+    processes started via \c start(), rather than \c exec().
+
+    \section2 getEnv
+    \code
+    getEnv(varName)
+    \endcode
+    Returns the value of the variable \c varName in the process' environment.
+
+    \section2 readLine
+    \code
+    readLine()
+    \endcode
+    Reads and returns one line of text from the process output, without the newline character(s).
+
+    \section2 readStdErr
+    \code
+    readStdErr()
+    \endcode
+    Reads and returns all data from the process' standard error channel.
+
+    \section2 readStdOut
+    \code
+    readStdOut()
+    \endcode
+    Reads and returns all data from the process' standard output channel.
+
+    \section2 setEnv
+    \code
+    setEnv(varName, varValue)
+    \endcode
+    Sets the value of variable \c varName to \c varValue in the process environment.
+    This only has an effect if called before the process is started.
+
+    \section2 start
+    \code
+    start(filePath, arguments)
+    \endcode
+    Starts the program at \c filePath with the given list of arguments. Returns true if the
+    process could be started and false otherwise.
+    \note This call returns right after starting the process and should be used only if you need
+    to interact with the process while it is running. Most of the time, you want to use \c exec()
+    instead.
+
+    \section2 waitForFinished
+    \code
+    waitForFinished(timeout)
+    \endcode
+    Blocks until the process has finished or \c timeout milliseconds have passed (default is 30000).
+    Returns true if the process has finished and false if the operation has timed out.
+    Calling this function only makes sense for processes started via \c start() (as opposed to
+    \c exec()).
+
+    \section2 write
+    \code
+    write(data)
+    \endcode
+    Writes \c data into the process' input channel.
+
+    \section2 writeLine
+    \code
+    writeLine(data)
+    \endcode
+    Writes \c data, followed by the newline character(s), into the process' input channel.
+*/
diff --git a/doc/reference/jsextensions/jsextension-textfile.qdoc b/doc/reference/jsextensions/jsextension-textfile.qdoc
new file mode 100644
index 000000000..4bc022240
--- /dev/null
+++ b/doc/reference/jsextensions/jsextension-textfile.qdoc
@@ -0,0 +1,108 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the Qt Build Suite.
+**
+** 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.
+**
+****************************************************************************/
+
+/*!
+    \contentspage index.html
+    \page jsextension-textfile.html
+    \ingroup list-of-builtin-services
+
+    \title The TextFile Service
+    \brief Provides read and write operations on text files.
+
+    The \c TextFile service allows you to read from and write into text files.
+
+    \section1 Making the service available
+    In order to gain access to these operations, you need to import the service using the
+    following statement at the top of your project file:
+    \code
+    import qbs.TextFile
+    \endcode
+
+    \section1 Available operations
+
+    \section2 Constructor
+    \code
+    TextFile(filePath, openMode)
+    \endcode
+    Opens the file at \c filePath in the given mode and returns the object representing the file.
+    Possible values for \c openMode are \c TextFile.ReadOnly (which is the default),
+    \c TextFile.WriteOnly and \c TextFile.ReadWrite. Note that the mode influences which
+    of the operations listed below can actually be used on the file.
+
+    \section2 atEof
+    \code
+    atEof()
+    \endcode
+    Returns true if no more data can be read from the file, false otherwise.
+
+    \section2 close
+    \code
+    close()
+    \endcode
+    Closes the file. We recommended to always call this function as soon as you are finished
+    with the file, in order to keep the number of in-flight file descriptors as low as possible.
+
+    \section2 readAll
+    \code
+    readAll()
+    \endcode
+    Reads all data from the file and returns it.
+
+    \section2 readLine
+    \code
+    readLine()
+    \endcode
+    Reads one line of text from the file and returns it. The returned string does not contain
+    the newline character(s).
+
+    \section2 setCodec
+    \code
+    setCodec(codec)
+    \endcode
+    Sets the text codec to \c codec. The supported codecs are the same as for \c QTextCodec,
+    e.g. "UTF-8", "UTF-16", "ISO 8859-1" and so on.
+
+    \section2 truncate
+    \code
+    truncate()
+    \endcode
+    Truncates the file, i.e. gives it a size of zero, removing all content.
+
+    \section2 write
+    \code
+    write(data)
+    \endcode
+    Writes \c data into the file at the current position.
+
+    \section2 writeLine
+    \code
+    writeLine(data)
+    \endcode
+    Writes \c data into the file at the current position and appends the newline character(s).
+*/
diff --git a/doc/reference/reference.qdoc b/doc/reference/reference.qdoc
index 09b824a78..feabe2ca4 100644
--- a/doc/reference/reference.qdoc
+++ b/doc/reference/reference.qdoc
@@ -35,13 +35,21 @@
 
     \list
         \li \l{List of Language Items}
-        \li \l{List of Built-in Services} [tbd]
+        \li \l{List of Built-in Services}
         \li \l{List of Modules}
     \endlist
 */
 
 /*!
     \contentspage reference.html
+    \group list-of-builtin-services
+    \title List of Built-in Services
+    Qbs provides the following built-in JavaScript extensions to simplify operations that
+    are expected to be needed often in project files.
+*/
+
+/*!
+    \contentspage reference.html
     \group list-of-modules
     \title List of Modules
     These are the modules shipped with qbs.