Uuid JSDoc

libraries/script-engine/src/ScriptUUID.h

@@ -18,11 +18,13 @@
 #include <QtScript/QScriptable>
 
 /**jsdoc
-* A UUID. Represented in JavaScript as a string in the format, <code>{00000000-0000-0000-0000-000000000000}</code>.
+ * A UUID (Universally Unique IDentitier) is used to uniquely identify entities, overlays, avatars, and the like. It is
-* Used to uniquely identify entities, overlays, avatars, and the like.
+ * represented in JavaScript as a string in the format, <code>{nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn}</code>, where the "n"s are
-*
+ * hexadecimal digits.
-* @typedef Uuid
+ *
-*/
+ * @namespace Uuid
+ * @property NULL {Uuid} The null UUID, <code>{00000000-0000-0000-0000-000000000000}</code>.
+ */
 
 /// Scriptable interface for a UUID helper class object. Used exclusively in the JavaScript API
 class ScriptUUID : public QObject, protected QScriptable {
@@ -31,10 +33,84 @@ class ScriptUUID : public QObject, protected QScriptable {
 
 public slots:
     QUuid fromString(const QString& string);
+    /**jsdoc
+     * Generates a UUID from a string representation of the UUID.
+     * @function Uuid.fromString
+     * @param {string} string - A string representation of a UUID. The curly braces are optional.
+     * @returns {Uuid} A UUID if the given <code>string</code> is valid, <code>null</code> otherwise.
+     * @example <caption>Valid and invalid parameters.</caption>
+     * var uuid = Uuid.fromString("{527c27ea-6d7b-4b47-9ae2-b3051d50d2cd}");
+     * print(uuid); // {527c27ea-6d7b-4b47-9ae2-b3051d50d2cd}
+     *
+     * uuid = Uuid.fromString("527c27ea-6d7b-4b47-9ae2-b3051d50d2cd");
+     * print(uuid); // {527c27ea-6d7b-4b47-9ae2-b3051d50d2cd}
+     *
+     * uuid = Uuid.fromString("527c27ea");
+     * print(uuid); // null
+     */
+
+    /**jsdoc
+     * Generates a string representation of a UUID. However, because UUIDs are represented in JavaScript as strings, this is in
+     * effect a no-op.
+     * @function Uuid.toString
+     * @param {Uuid} id - The UUID to generate a string from.
+     * @returns {string} - A string representation of the UUID.
+     */
     QString toString(const QUuid& id);
+    
+    /**jsdoc
+     * Generate a new UUID.
+     * @function Uuid.generate
+     * @returns {Uuid} A new UUID.
+     * @example <caption>Generate a new UUID and reports its JavaScript type.</caption>
+     * var uuid = Uuid.generate();
+     * print(uuid);        // {nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn}
+     * print(typeof uuid); // string
+     */
     QUuid generate();
+
+    /**jsdoc
+     * Test whether two given UUIDs are equal.
+     * @function Uuid.isEqual
+     * @param {Uuid} idA - The first UUID to compare.
+     * @param {Uuid} idB - The second UUID to compare.
+     * @returns {boolean} <code>true</code> if the two UUIDs are equal, otherwise <code>false</code>.
+     * @example <caption>Demonstrate <code>true</code> and <code>false</code> cases.</caption>
+     * var uuidA = Uuid.generate();
+     * var uuidB = Uuid.generate();
+     * print(Uuid.isEqual(uuidA, uuidB)); // false
+     * uuidB = uuidA;
+     * print(Uuid.isEqual(uuidA, uuidB)); // true
+     */
     bool isEqual(const QUuid& idA, const QUuid& idB);
+
+    /**jsdoc
+     * Test whether a given UUID is null.
+     * @function Uuid.isNull
+     * @param {Uuid} id - The UUID to test.
+     * @returns {boolean} <code>true</code> if the UUID equals Uuid.NULL or is <code>null</code>, otherwise <code>false</code>.
+     * @example <caption>Demonstrate <code>true</code> and <code>false</code> cases.</caption>
+     * var uuid; // undefined
+     * print(Uuid.isNull(uuid)); // false
+     * uuid = Uuid.generate();
+     * print(Uuid.isNull(uuid)); // false
+     * uuid = Uuid.NULL;
+     * print(Uuid.isNull(uuid)); // true
+     * uuid = null;
+     * print(Uuid.isNull(uuid)); // true
+     */
     bool isNull(const QUuid& id);
+
+    /**jsdoc
+     * Print to the program log a text label followed by the UUID value.
+     * @function Uuid.print
+     * @param {string} label - The label to print.
+     * @param {Uuid} id - The UUID to print.
+     * @example <caption>Two ways of printing a label plus UUID.</caption>
+     * var uuid = Uuid.generate();
+     * Uuid.print("Generated UUID:", uuid); // Generated UUID: {nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn}
+     * print("Generated UUID: " + uuid);    // Generated UUID: {nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn}
+     */
     void print(const QString& label, const QUuid& id);
 
 private: