Annotate parameter and return types in Service documentation.

This uses a declaration style similar to what is used by TypeScript.

Change-Id: I5fb7ace4bb778e294b43eae72bff7c2b672795c3
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@digia.com>

7 files changed, 105 insertions, 103 deletions

diff --git a/doc/reference/jsextensions/jsextension-file.qdoc b/doc/reference/jsextensions/jsextension-file.qdoc
index fb13a650d..c9d192826 100644
--- a/doc/reference/jsextensions/jsextension-file.qdoc
+++ b/doc/reference/jsextensions/jsextension-file.qdoc
@@ -38,18 +38,11 @@
     The \c File service offers limited access to the file system for operations such as copying
     or removing files.
 
-    \section1 Making the Service Available
-    To gain access to file system operations, 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)
+    File.copy(sourceFilePath: string, targetFilePath: string): boolean
     \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
@@ -60,13 +53,13 @@
 
     \section2 exists
     \code
-    File.exists(filePath)
+    File.exists(filePath: string): boolean
     \endcode
     Returns true if and only if there is a file at \c filePath.
 
     \section2 lastModified
     \code
-    File.lastModified(filePath)
+    File.lastModified(filePath: string): number
     \endcode
     Returns the time of last modification for the file at \c filePath. The concrete semantics of the
     returned value are platform-specific. You should only rely on the property that a smaller value
@@ -74,7 +67,7 @@
 
     \section2 remove
     \code
-    File.remove(filePath)
+    File.remove(filePath: string): boolean
     \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
index 21cd0a67a..ba08cc6f9 100644
--- a/doc/reference/jsextensions/jsextension-fileinfo.qdoc
+++ b/doc/reference/jsextensions/jsextension-fileinfo.qdoc
@@ -38,56 +38,48 @@
     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 file path 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)
+    FileInfo.baseName(filePath: string): string
     \endcode
     Returns the file name of \c filePath up to (but not including) the first '.' character.
 
     \section2 completeBaseName
     \code
-    FileInfo.completeBaseName(filePath)
+    FileInfo.completeBaseName(filePath: string): string
     \endcode
     Returns the file name of \c filePath up to (but not including) the last '.' character.
 
     \section2 fileName
     \code
-    FileInfo.fileName(filePath)
+    FileInfo.fileName(filePath: string): string
     \endcode
     Returns the last component of \c filePath, that is, everything after the
     last '/' character.
 
     \section2 fromWindowsSeparators
     \code
-    FileInfo.fromWindowsSeparators(filePath)
+    FileInfo.fromWindowsSeparators(filePath: string): string
     \endcode
     Returns \c filePath with all '\\' characters replaced by '/'.
 
     \section2 isAbsolutePath
     \code
-    FileInfo.isAbsolutPath(filePath)
+    FileInfo.isAbsolutePath(filePath: string): boolean
     \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, ...)
+    FileInfo.joinPaths(...paths: string[]): string
     \endcode
     Concatenates the given paths using the '/' character.
 
     \section2 path
     \code
-    FileInfo.path(filePath)
+    FileInfo.path(filePath: string): string
     \endcode
     Returns the part of \c filePath that is not the file name, that is,
     everything up to
@@ -97,7 +89,7 @@
 
     \section2 relativePath
     \code
-    FileInfo.relativePath(dirPath, filePath)
+    FileInfo.relativePath(dirPath: string, filePath: string): string
     \endcode
     Returns a relative path so that joining \c dirPath and the returned path results in \c filePath.
     If necessary, '..' components are inserted.
@@ -106,7 +98,7 @@
 
     \section2 toWindowsSeparators
     \code
-    FileInfo.toWindowsSeparators(filePath)
+    FileInfo.toWindowsSeparators(filePath: string): string
     \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
index 61b83da09..765a54c6c 100644
--- a/doc/reference/jsextensions/jsextension-process.qdoc
+++ b/doc/reference/jsextensions/jsextension-process.qdoc
@@ -38,14 +38,6 @@
     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 process management 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
@@ -56,14 +48,14 @@
 
     \section2 close
     \code
-    close()
+    close(): void
     \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)
+    exec(filePath: string, arguments: string[], throwOnError: boolean): number
     \endcode
     Executes the program at \c filePath with the given argument list and blocks until the
     process is finished. If an error occurs (for example, there is no executable
@@ -74,75 +66,75 @@
 
     \section2 exitCode
     \code
-    exitCode()
+    exitCode(): number
     \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)
+    getEnv(varName: string): string
     \endcode
     Returns the value of the variable \c varName in the process' environment.
 
     \section2 kill
     \code
-    kill()
+    kill(): void
     \endcode
     Kills the process, causing it to exit immediately.
 
     \section2 readLine
     \code
-    readLine()
+    readLine(): string
     \endcode
     Reads and returns one line of text from the process output, without the newline character(s).
 
     \section2 readStdErr
     \code
-    readStdErr()
+    readStdErr(): string
     \endcode
     Reads and returns all data from the process' standard error channel.
 
     \section2 readStdOut
     \code
-    readStdOut()
+    readStdOut(): string
     \endcode
     Reads and returns all data from the process' standard output channel.
 
     \section2 setEnv
     \code
-    setEnv(varName, varValue)
+    setEnv(varName: string, varValue: string): string
     \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 setWorkingDirectory
     \code
-    setWorkingDirectory(dir)
+    setWorkingDirectory(path: string): void
     \endcode
     Sets the directory the process will be started in.
     This only has an effect if called before the process is started.
 
     \section2 start
     \code
-    start(filePath, arguments)
+    start(filePath: string, arguments: string[]): boolean
     \endcode
-    Starts the program at \c filePath with the given list of arguments. Returns true if the
-    process could be started and false otherwise.
+    Starts the program at \c filePath with the given list of arguments. Returns \c{true} if the
+    process could be started and \c{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 terminate
     \code
-    terminate()
+    terminate(): void
     \endcode
     Tries to terminate the process. This is not guaranteed to make the process exit immediately;
     if you need that, use \c kill().
 
     \section2 waitForFinished
     \code
-    waitForFinished(timeout)
+    waitForFinished(timeout: number): boolean
     \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.
@@ -151,19 +143,19 @@
 
     \section2 workingDirectory
     \code
-    \workingDirectory()
+    workingDirectory(): string
     \endcode
     Returns the directory the process will be started in.
 
     \section2 write
     \code
-    write(data)
+    write(data: string): void
     \endcode
     Writes \c data into the process' input channel.
 
     \section2 writeLine
     \code
-    writeLine(data)
+    writeLine(data: string): void
     \endcode
     Writes \c data, followed by the newline character(s), into the process' input channel.
 */
diff --git a/doc/reference/jsextensions/jsextension-propertylist.qdoc b/doc/reference/jsextensions/jsextension-propertylist.qdoc
index 744f37da1..c5fd5e0ff 100644
--- a/doc/reference/jsextensions/jsextension-propertylist.qdoc
+++ b/doc/reference/jsextensions/jsextension-propertylist.qdoc
@@ -41,14 +41,6 @@
 
     This service is only available on Darwin platforms such as OS X and iOS.
 
-    \section1 Making the Service Available
-    In order to gain access to property list operations, you need to import the
-    service using the
-    following statement at the top of your project file:
-    \code
-    import qbs.PropertyList
-    \endcode
-
     \section1 Available operations
 
     \section2 Constructor
@@ -59,19 +51,19 @@
 
     \section2 clear
     \code
-    clear()
+    clear(): void
     \endcode
     Voids the property list by deleting its internal object reference.
 
     \section2 isEmpty
     \code
-    isEmpty()
+    isEmpty(): boolean
     \endcode
     Returns true if the property list has no internal object reference set, otherwise false.
 
     \section2 format
     \code
-    format()
+    format(): string
     \endcode
     Returns the data format that the property list data was deserialized from. This property is set
     after calling \c readFromString or \c readFromFile.
@@ -81,14 +73,14 @@
 
     \section2 readFromFile
     \code
-    readFromFile(filePath)
+    readFromFile(filePath: string): void
     \endcode
     Parses the file and stores the result in the property list.
     Throws an exception if an I/O error occurs or the input is in an invalid format.
 
     \section2 readFromString
     \code
-    readFromString(input)
+    readFromString(input: string): void
     \endcode
     Parses \c input and stores the result in the property list.
     This is most useful for initializing a property list object from the result of a
@@ -97,14 +89,14 @@
 
     \section2 toJSONString
     \code
-    toJSONString(style)
+    toJSONString(style: string = "compact"): string
     \endcode
     Returns a string representation of the property list in JSON format.
     Possible values for \c style include \c "pretty" and \c "compact". The default is compact.
 
     \section2 toString
     \code
-    toString(format)
+    toString(format: string): string
     \endcode
     Returns a string representation of the property list in the specified format.
     Possible values for \c format include: \c "json" (compact), \c "json-compact", \c "json-pretty",
@@ -113,14 +105,14 @@
 
     \section2 toXMLString
     \code
-    toXMLString()
+    toXMLString(): string
     \endcode
     Returns a string representation of the property list in XML format.
     This function is a synonym for \c toString("xml1").
 
     \section2 writeToFile
     \code
-    writeToFile(filePath, format)
+    writeToFile(filePath: string, format: string): void
     \endcode
     Writes the property list to the file in the given format.
     Possible values for \c format include: \c "binary1", \c "json" (compact), \c "json-compact",
diff --git a/doc/reference/jsextensions/jsextension-textfile.qdoc b/doc/reference/jsextensions/jsextension-textfile.qdoc
index 9700a3b39..f386d89e0 100644
--- a/doc/reference/jsextensions/jsextension-textfile.qdoc
+++ b/doc/reference/jsextensions/jsextension-textfile.qdoc
@@ -37,73 +37,71 @@
 
     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 text file operations, you need to import the
-    service using the
-    following statement at the top of your project file:
+    \section1 Related Declarations
+
+    \section2 TextFile.OpenMode
     \code
-    import qbs.TextFile
+    enum TextFile.OpenMode { ReadOnly, WriteOnly, ReadWrite }
     \endcode
+    List of modes that a file may be opened in.
 
     \section1 Available operations
 
     \section2 Constructor
     \code
-    TextFile(filePath, openMode)
+    TextFile(filePath: string, openMode: OpenMode = TextFile.ReadOnly)
     \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.
+    \note The mode influences which of the operations listed below can actually be used on the file.
 
     \section2 atEof
     \code
-    atEof()
+    atEof(): boolean
     \endcode
-    Returns true if no more data can be read from the file, false otherwise.
+    Returns \c{true} if no more data can be read from the file, \c{false} otherwise.
 
     \section2 close
     \code
-    close()
+    close(): void
     \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()
+    readAll(): string
     \endcode
     Reads all data from the file and returns it.
 
     \section2 readLine
     \code
-    readLine()
+    readLine(): string
     \endcode
     Reads one line of text from the file and returns it. The returned string does not contain
     the newline characters.
 
     \section2 setCodec
     \code
-    setCodec(codec)
+    setCodec(codec: string): void
     \endcode
     Sets the text codec to \c codec. The supported codecs are the same as for \c QTextCodec,
     for example: "UTF-8", "UTF-16", and "ISO 8859-1".
 
     \section2 truncate
     \code
-    truncate()
+    truncate(): void
     \endcode
     Truncates the file, that is, gives it the size of zero, removing all content.
 
     \section2 write
     \code
-    write(data)
+    write(data: string): void
     \endcode
     Writes \c data into the file at the current position.
 
     \section2 writeLine
     \code
-    writeLine(data)
+    writeLine(data: string): void
     \endcode
     Writes \c data into the file at the current position and appends the newline character(s).
 */
diff --git a/doc/reference/jsextensions/jsextensions-general.qdoc b/doc/reference/jsextensions/jsextensions-general.qdoc
index 9c09849e1..58c5c74f4 100644
--- a/doc/reference/jsextensions/jsextensions-general.qdoc
+++ b/doc/reference/jsextensions/jsextensions-general.qdoc
@@ -36,20 +36,20 @@
     \brief Provides various operations.
 
     These are operations that do not fit into any of the other categories.
-    They are automatically available in any \QBS project file.
+    They are automatically available in any \QBS project file or JavaScript file.
 
     \section1 Available Operations
 
-    \section2 getEnv
+    \section2 qbs.getEnv
     \code
-    qbs.getEnv(name)
+    qbs.getEnv(key: string): string
     \endcode
     Tries to find a variable with the given name in the build environment and returns its value. If
     no such variable could be found, \c undefined is returned.
 
-    \section2 getHostOS
+    \section2 qbs.getHostOS
     \code
-    qbs.getHostOS(name)
+    qbs.getHostOS(): string
     \endcode
     Returns the name of the operating system on which \QBS is running.
     \note Do not confuse this with the \c{qbs.targetOS} property, which represents the operating
@@ -57,37 +57,60 @@
 
     \section2 loadFile
     \code
-    var MyFunctions = loadFile("myfunctions.js");
-    MyFunctions.doSomething();
+    loadFile(filePath: string): any
     \endcode
     Loads a JavaScript file and returns an object that contains the evaluated context of this file.
     This function is only available in JavaScript files.
+    For example:
+    \code
+    var MyFunctions = loadFile("myfunctions.js");
+    MyFunctions.doSomething();
+    \endcode
 
     \section2 loadExtension
     \code
-    var FileInfo = loadExtension("qbs.FileInfo");
-    var fileName = FileInfo.fileName(filePath);
+    loadExtension(extensionName: string): any
     \endcode
     Loads a \QBS extension and returns an object that contains all functions of that extension.
     This function is only available in JavaScript files.
+    For example:
+    \code
+    var FileInfo = loadExtension("qbs.FileInfo");
+    var fileName = FileInfo.fileName(filePath);
+    \endcode
 
 
     \section1 Extensions to JavaScript Built-in Objects
 
-    \section2 \c{Array.contains(e)}
+    \section2 Array.contains
+    \code
+    Array.contains(e: any): boolean
+    \endcode
     Returns \c{true} if the array contains the element \c{e}. Returns \c{false} otherwise.
 
-    \section2 \c{Array.uniqueConcat(other)}
+    \section2 Array.uniqueConcat
+    \code
+    Array.uniqueConcat(other: any[]): any[]
+    \endcode
     Returns a copy of this array joined with the array \c{other}.
     Duplicates that would originate from the concatenation are removed.
     The order of elements is preserved.
 
-    \section2 \c{String.contains(s)}
+    \section2 String.contains
+    \code
+    String.contains(s: string): boolean
+    \endcode
     Returns \c{true} if the string contains the substring \c{s}. Returns \c{false} otherwise.
 
-    \section2 \c{String.startsWith(s)}
+    \section2 startsWith
+    \code
+    String.startsWith(s: string): boolean
+    \endcode
     Returns \c{true} if the string starts with the substring \c{s}. Returns \c{false} otherwise.
 
-    \section2 \c{String.endsWith(s)}
+    \section2 endsWith
+    \code
+    String.endsWith(s: string): boolean
+    \endcode
     Returns \c{true} if the string ends with the substring \c{s}. Returns \c{false} otherwise.
 */
diff --git a/doc/reference/reference.qdoc b/doc/reference/reference.qdoc
index b583a8b55..e38267278 100644
--- a/doc/reference/reference.qdoc
+++ b/doc/reference/reference.qdoc
@@ -47,6 +47,18 @@
     \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.
+
+    To gain access to the operations provided by a particular Service - for example,
+    the File service - use the following statement at the top of your \QBS project file:
+    \code
+    import qbs.File
+    \endcode
+
+    If you instead need to access the service from a JavaScript file, import it using the following
+    statement at the top of your JavaScript file:
+    \code
+    var File = loadExtension("qbs.File");
+    \endcode
 */
 
 /*!