Merge pull request #9042 from hyperlogic/feature/jsdoc

Generate JS documentation from comments in C++ source

interface/src/scripting/AccountScriptingInterface.h

@@ -19,12 +19,35 @@ class AccountScriptingInterface : public QObject {
 
     Q_PROPERTY(QString username READ getUsername NOTIFY usernameChanged)
 
+    /**jsdoc
+     * @namespace Account
+     * @property username {String} username if user is logged in, otherwise it returns "Unknown user"
+     */
+
 signals:
+
+    /**jsdoc
+     * Triggered when username has changed.
+     * @function Account.usernameChanged
+     * @return {Signal}
+     */
     void usernameChanged();
 
 public slots:
     static AccountScriptingInterface* getInstance();
+
+    /**jsdoc
+     * Returns the username for the currently logged in High Fidelity metaverse account.
+     * @function Account.getUsername
+     * @return {string} username if user is logged in, otherwise it returns "Unknown user"
+     */
     QString getUsername();
+
+    /**jsdoc
+     * Determine if the user is logged into the High Fidleity metaverse.
+     * @function Account.isLoggedIn
+     * @return {bool} true when user is logged into the High Fidelity metaverse.
+     */
     bool isLoggedIn();
     bool checkAndSignalForAccessToken();
 };

libraries/animation/src/AnimationCache.h

@@ -29,7 +29,19 @@ class AnimationCache : public ResourceCache, public Dependency  {
     Q_OBJECT
     SINGLETON_DEPENDENCY
 
+    /**jsdoc
+     * @namespace AnimationCache
+     * @augments ResourceCache
+     */
+
 public:
+
+    /**jsdoc
+     * Returns animation resource for particular animation
+     * @function AnimationCache.getAnimation
+     * @param url {string} url to load
+     * @return {Resource} animation
+     */
     Q_INVOKABLE AnimationPointer getAnimation(const QString& url) { return getAnimation(QUrl(url)); }
     Q_INVOKABLE AnimationPointer getAnimation(const QUrl& url);
 

libraries/networking/src/ResourceCache.h

@@ -88,7 +88,24 @@ class ScriptableResource : public QObject {
     Q_PROPERTY(QUrl url READ getUrl)
     Q_PROPERTY(int state READ getState NOTIFY stateChanged)
 
+    /**jsdoc
+     * @constructor Resource
+     * @property url {string} url of this resource
+     * @property state {Resource.State} current loading state
+     */
+
 public:
+
+    /**jsdoc
+     * @name Resource.State
+     * @static
+     * @property QUEUED {int} The resource is queued up, waiting to be loaded.
+     * @property LOADING {int} The resource is downloading
+     * @property LOADED {int} The resource has finished downloaded by is not complete
+     * @property FINISHED {int} The resource has completly finished loading and is ready.
+     * @property FAILED {int} Downloading the resource has failed.
+     */
+
     enum State {
         QUEUED,
         LOADING,
@@ -101,6 +118,10 @@ public:
     ScriptableResource(const QUrl& url);
     virtual ~ScriptableResource() = default;
 
+    /**jsdoc
+     * Release this resource
+     * @function Resource#release
+     */
     Q_INVOKABLE void release();
 
     const QUrl& getUrl() const { return _url; }
@@ -111,7 +132,22 @@ public:
     void setInScript(bool isInScript);
 
 signals:
+
+    /**jsdoc
+     * Signaled when download progress for this resource has changed
+     * @function Resource#progressChanged
+     * @param bytesReceived {int} bytes downloaded so far
+     * @param bytesTotal {int} total number of bytes in the resource
+     * @returns {Signal}
+     */
     void progressChanged(uint64_t bytesReceived, uint64_t bytesTotal);
+
+    /**jsdoc
+     * Signaled when resource loading state has changed
+     * @function Resource#stateChanged
+     * @param bytesReceived {Resource.State} new state
+     * @returns {Signal}
+     */
     void stateChanged(int state);
 
 protected:
@@ -148,14 +184,49 @@ class ResourceCache : public QObject {
     Q_PROPERTY(size_t numCached READ getNumCachedResources NOTIFY dirty)
     Q_PROPERTY(size_t sizeTotal READ getSizeTotalResources NOTIFY dirty)
     Q_PROPERTY(size_t sizeCached READ getSizeCachedResources NOTIFY dirty)
-    
+
+    /**jsdoc
+     * @namespace ResourceCache
+     * @property numTotal {number} total number of total resources
+     * @property numCached {number} total number of cached resource
+     * @property sizeTotal {number} size in bytes of all resources
+     * @property sizeCached {number} size in bytes of all cached resources
+     */
+
 public:
+    /**jsdoc
+     * Returns the total number of resources
+     * @function ResourceCache.getNumTotalResources
+     * @return {number}
+     */
     size_t getNumTotalResources() const { return _numTotalResources; }
+
+    /**jsdoc
+     * Returns the total size in bytes of all resources
+     * @function ResourceCache.getSizeTotalResources
+     * @return {number}
+     */
     size_t getSizeTotalResources() const { return _totalResourcesSize; }
 
+    /**jsdoc
+     * Returns the total number of cached resources
+     * @function ResourceCache.getNumCachedResources
+     * @return {number}
+     */
     size_t getNumCachedResources() const { return _numUnusedResources; }
+
+    /**jsdoc
+     * Returns the total size in bytes of cached resources
+     * @function ResourceCache.getSizeCachedResources
+     * @return {number}
+     */
     size_t getSizeCachedResources() const { return _unusedResourcesSize; }
 
+    /**jsdoc
+     * Returns list of all resource urls
+     * @function ResourceCache.getResourceList
+     * @return {string[]}
+     */
     Q_INVOKABLE QVariantList getResourceList();
 
     static void setRequestLimit(int limit);
@@ -192,6 +263,13 @@ protected slots:
     /// returns an empty smart pointer and loads its asynchronously.
     /// \param fallback a fallback URL to load if the desired one is unavailable
     /// \param extra extra data to pass to the creator, if appropriate
+    /**jsdoc
+     * Asynchronously loads a resource from the spedified URL and returns it.
+     * @param url {string} url of resource to load
+     * @param fallback {string} fallback URL if load of the desired url fails
+     * @function ResourceCache.getResource
+     * @return {Resource}
+     */
     QSharedPointer<Resource> getResource(const QUrl& url, const QUrl& fallback = QUrl(),
         void* extra = NULL);
 
@@ -203,6 +281,12 @@ protected:
     // Pointers created through this method should be owned by the caller,
     // which should be a QScriptEngine with ScriptableResource registered, so that
     // the QScriptEngine will delete the pointer when it is garbage collected.
+    /**jsdoc
+     * Prefetches a resource.
+     * @param url {string} url of resource to load
+     * @function ResourceCache.prefetch
+     * @return {Resource}
+     */
     Q_INVOKABLE ScriptableResource* prefetch(const QUrl& url) { return prefetch(url, nullptr); }
 
     /// Creates a new resource.

libraries/script-engine/src/AssetScriptingInterface.h

@@ -19,13 +19,60 @@
 
 #include <AssetClient.h>
 
+/**jsdoc
+ * @namespace Assets
+ */
 class AssetScriptingInterface : public QObject {
     Q_OBJECT
 public:
     AssetScriptingInterface(QScriptEngine* engine);
 
+    /**jsdoc
+     * Upload content to the connected domain's asset server.
+     * @function Assets.uploadData
+     * @static
+     * @param data {string} content to upload
+     * @param callback {Assets~uploadDataCallback} called when upload is complete
+     */
+
+    /**jsdoc
+     * Called when uploadData is complete
+     * @callback Assets~uploadDataCallback
+     * @param {string} url
+     * @param {string} hash
+     */
+
     Q_INVOKABLE void uploadData(QString data, QScriptValue callback);
+
+    /**jsdoc
+     * Download data from the connected domain's asset server.
+     * @function Assets.downloadData
+     * @static
+     * @param url {string} url of asset to download, must be atp scheme url.
+     * @param callback {Assets~downloadDataCallback}
+     */
+
+    /**jsdoc
+     * Called when downloadData is complete
+     * @callback Assets~downloadDataCallback
+     * @param data {string} content that was downloaded
+     */
+
     Q_INVOKABLE void downloadData(QString url, QScriptValue downloadComplete);
+
+    /**jsdoc
+     * Sets up a path to hash mapping within the connected domain's asset server
+     * @function Assets.setMapping
+     * @static
+     * @param path {string}
+     * @param hash {string}
+     * @param callback {Assets~setMappingCallback}
+     */
+
+    /**jsdoc
+     * Called when setMapping is complete
+     * @callback Assets~setMappingCallback
+     */
     Q_INVOKABLE void setMapping(QString path, QString hash, QScriptValue callback);
 
 #if (PR_BUILD || DEV_BUILD)

tools/jsdoc/.gitignore

@@ -0,0 +1 @@
+out

tools/jsdoc/README.md

@@ -0,0 +1,13 @@
+#JavaScript Documentation Generation
+
+##Prerequisites
+
+* Install node.js
+* Install jsdoc via npm.  `npm install jsdoc -g`
+
+To generate html documentation for the High Fidelity JavaScript API
+
+`cd scripts/jsdoc`
+`jsdoc . -c config.json`
+
+The out folder should contain index.html

tools/jsdoc/config.json

@@ -0,0 +1,8 @@
+{
+    "templates": {
+        "default": {
+            "outputSourceFiles": false
+        }
+    },
+    "plugins": ["plugins/hifi"]
+}

tools/jsdoc/plugins/hifi.js

@@ -0,0 +1,41 @@
+function endsWith(path, exts) {
+    var result = false;
+    exts.forEach(function(ext) {
+        if (path.endsWith(ext)) {
+            result = true;
+        }
+    });
+    return result;
+}
+
+exports.handlers = {
+    beforeParse: function(e) {
+        console.log("Scanning hifi source for jsdoc comments...");
+
+        // directories to scan for jsdoc comments
+        var dirList = [
+            '../../interface/src',
+            '../../interface/src/scripting',
+            '../../libraries/script-engine/src',
+            '../../libraries/networking/src',
+            '../../libraries/animation/src',
+        ];
+        var exts = ['.h', '.cpp'];
+
+        const fs = require('fs');
+        dirList.forEach(function (dir) {
+            var files = fs.readdirSync(dir)
+            files.forEach(function (file) {
+                var path = dir + "/" + file;
+                if (fs.lstatSync(path).isFile() && endsWith(path, exts)) {
+                    var data = fs.readFileSync(path, "utf8");
+                    var reg = /(\/\*\*jsdoc(.|[\r\n])*?\*\/)/gm;
+                    var matches = data.match(reg);
+                    if (matches) {
+                        e.source += matches.map(function (s) { return s.replace('/**jsdoc', '/**'); }).join('\n');
+                    }
+                }
+            });
+        });
+    }
+};

tools/jsdoc/root.js

@@ -0,0 +1,11 @@
+//
+//  root.js
+//
+//  Copyright 2016 High Fidelity, Inc.
+//
+//  Distributed under the Apache License, Version 2.0.
+//  See the accompanying file LICENSE or http://www.apache.org/licenses/LICENSE-2.0.html
+//
+//  Root of High Fidelity generated java script documentation
+//
+