From 7183d108790f68edea01fe7af51e212a140775a2 Mon Sep 17 00:00:00 2001
From: David Rowe <david@ctrlaltstudio.com>
Date: Mon, 6 May 2019 10:26:16 +1200
Subject: [PATCH] Desktop JSDoc

---
 .../scripting/DesktopScriptingInterface.cpp   |  7 +++
 .../src/scripting/DesktopScriptingInterface.h | 51 +++++++++++++++++--
 2 files changed, 54 insertions(+), 4 deletions(-)

diff --git a/interface/src/scripting/DesktopScriptingInterface.cpp b/interface/src/scripting/DesktopScriptingInterface.cpp
index bda06cda48..f6c089b17c 100644
--- a/interface/src/scripting/DesktopScriptingInterface.cpp
+++ b/interface/src/scripting/DesktopScriptingInterface.cpp
@@ -31,6 +31,13 @@ int DesktopScriptingInterface::getHeight() {
     return size.height();
 }
 
+/**jsdoc
+ * The presentation mode specifies how an {@link InteractiveWindow} is displayed.
+ * @typedef {object} InteractiveWindow.PresentationMode
+ * @property {number} VIRTUAL - The window is displayed inside Interface: in the desktop window in desktop mode or on the HUD 
+ *     surface in HMD mode.
+ * @property {number} NATIVE - The window is displayed separately from the Interface window, as its own separate window.
+ */
 QVariantMap DesktopScriptingInterface::getPresentationMode() {
     static QVariantMap presentationModes {
         { "VIRTUAL", Virtual },
diff --git a/interface/src/scripting/DesktopScriptingInterface.h b/interface/src/scripting/DesktopScriptingInterface.h
index c8e251eb3e..2711447b45 100644
--- a/interface/src/scripting/DesktopScriptingInterface.h
+++ b/interface/src/scripting/DesktopScriptingInterface.h
@@ -20,16 +20,25 @@
 #include "InteractiveWindow.h"
 
 /**jsdoc
+ * The <code>Desktop</code> API provides the dimensions of the computer screen, sets the opacity of the HUD surface, and 
+ * enables QML and HTML windows to be shown inside or outside of Interface.
+  *
  * @namespace Desktop
  *
  * @hifi-interface
  * @hifi-client-entity
  * @hifi-avatar
  *
- * @property {number} width
- * @property {number} height
- * @property {number} ALWAYS_ON_TOP - InteractiveWindow flag for always showing a window on top
- * @property {number} CLOSE_BUTTON_HIDES - InteractiveWindow flag for hiding the window instead of closing on window close by user
+ * @property {number} width - The width of the computer screen including task bar and system menu, in pixels. 
+ *     <em>Read-only.</em>
+ * @property {number} height - The height of the computer screen including task bar and system menu, in pixels. 
+ *     <em>Read-only.</em>
+ * @property {InteractiveWindow.Flags} ALWAYS_ON_TOP - A flag value that makes an {@link InteractiveWindow} always display on 
+ *     top. <em>Read-only.</em>
+ * @property {InteractiveWindow.Flags} CLOSE_BUTTON_HIDES - A flag value that makes an {@link InteractiveWindow} hide instead 
+ *     of closing when the user clicks the "close" button.<em> Read-only.</em>
+ * @property {InteractiveWindow.PresentationMode} PresentationMode - The different display options for an 
+ *     {@link InteractiveWindow}: display inside Interface or in a separate desktop window. <em>Read-only.</em>
  */
 class DesktopScriptingInterface : public QObject, public Dependency {
     Q_OBJECT
@@ -41,9 +50,43 @@ class DesktopScriptingInterface : public QObject, public Dependency {
     Q_PROPERTY(int CLOSE_BUTTON_HIDES READ flagCloseButtonHides CONSTANT FINAL)
 
 public:
+    /**jsdoc
+     * Sets the opacity of the HUD surface.
+     * @function Desktop.setHUDAlpha
+     * @param {number} alpha - The opacity, <code>0.0 &ndash; 1.0</code>.
+     */
     Q_INVOKABLE void setHUDAlpha(float alpha);
+
+    /**jsdoc
+     * Opens a QML window within Interface: in the Interface window in desktop mode or on the HUD surface in HMD mode. If a 
+     * window of the specified name already exists, it is shown, otherwise a new window is created from the QML.
+     * @function Desktop.show
+     * @param {string} url - The QML file that specifies the window content
+     * @param {string} name - A unique name for the window.
+     * @example <caption>Open the general settings dialog.</caption>
+     * Desktop.show("hifi/dialogs/GeneralPreferencesDialog.qml", "GeneralPreferencesDialog");
+     */
     Q_INVOKABLE void show(const QString& path, const QString&  title);
 
+    /**jsdoc
+     * Creates a new window that can be displayed either within Interface or as a separate desktop window.
+     * @function Desktop.createWindow
+     * @param {string} url - The QML file that specifies the window content. The QML file can use a <code>WebView</code> 
+     *     control (defined by "WebView.qml" included in the Interface install) to embed an HTML Web page (complete with  
+     *     <code>EventBridge</code> object).
+     * @param {InteractiveWindow.Properties} [properties] - Initial window properties.
+     * @returns {InteractiveWindow} A new window object.
+     * @example <caption>Open a dialog in its own window separate from Interface.</caption>
+     * var nativeWindow = Desktop.createWindow(Script.resourcesPath() + 'qml/OverlayWindowTest.qml', {
+     *     title: "Native Window",
+     *     presentationMode: Desktop.PresentationMode.NATIVE,
+     *     size: { x: 500, y: 400 }
+     * });
+     *
+     * Script.scriptEnding.connect(function () {
+     *     nativeWindow.close();
+     * });
+     */
     Q_INVOKABLE InteractiveWindowPointer createWindow(const QString& sourceUrl, const QVariantMap& properties = QVariantMap());
 
     int getWidth();