diff --git a/libraries/script-engine/src/ScriptUUID.h b/libraries/script-engine/src/ScriptUUID.h index 5b5726ea83..bf828f5646 100644 --- a/libraries/script-engine/src/ScriptUUID.h +++ b/libraries/script-engine/src/ScriptUUID.h @@ -18,11 +18,13 @@ #include /**jsdoc -* A UUID. Represented in JavaScript as a string in the format, {00000000-0000-0000-0000-000000000000}. -* Used to uniquely identify entities, overlays, avatars, and the like. -* -* @typedef Uuid -*/ + * A UUID (Universally Unique IDentitier) is used to uniquely identify entities, overlays, avatars, and the like. It is + * represented in JavaScript as a string in the format, {nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn}, where the "n"s are + * hexadecimal digits. + * + * @namespace Uuid + * @property NULL {Uuid} The null UUID, {00000000-0000-0000-0000-000000000000}. + */ /// 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 string is valid, null otherwise. + * @example Valid and invalid parameters. + * 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 Generate a new UUID and reports its JavaScript type. + * 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} true if the two UUIDs are equal, otherwise false. + * @example Demonstrate true and false cases. + * 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} true if the UUID equals Uuid.NULL or is null, otherwise false. + * @example Demonstrate true and false cases. + * 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 Two ways of printing a label plus UUID. + * 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: