Sometimes there are hidden/private properties on class/item.
To document them, a possibility should be added to mark them as private/hidden/shadow.
E.g.:
class Notification{
constructor(title, message) {
let { error, value } = Notification.validate({
title,
message
});
if (error) {
throw error;
}
// set/merge default values
Object.assign(this, value);
// hidden property
Object.defineProperty(this, "published", {
value: false,
writable: true
});
}
}
The published property is used for internal purpose only, but needs to be documented.
Typical documentation of a class looks like this:
/**
* @description
* Represents a room item
*
* @class Room
*
* @param {Object} obj Object that matches the item schema. See properties below:
*
* @property {String} _id MongoDB Object is as string
* @property {Number} [number=null] Room number
* @property {Number} [floor=null] Floor on which the room is located
* @property {String} [icon=null] fontawesome class string for the frontend
*/
But what about necessary/non default values props?:
/**
* @description
* Device item in component `.items` array
*
* @class Device
*
* @param {Object} props Object that matches the item schema. See properties below:
*
* @property {String} _id MongoDB Object id is as string
* @property {String} name Human readable name
* @property {String} room Simle identifier to find the secret when you need it
* @property {Boolean} enabled Can we read/write data to/from the device
* @property {Array} interfaces Objects that match the interface schema
*
* @see interface components/devices/class.interface.js
* @see interfaceStream components/devices/class.interfaceStream.js
*/
@property {String} name,shadow=true Human readable name
@property {String} name,hidden Human readable name
Sometimes there are hidden/private properties on class/item. To document them, a possibility should be added to mark them as private/hidden/shadow.
E.g.:
The
publishedproperty is used for internal purpose only, but needs to be documented. Typical documentation of a class looks like this:Add a flag/bit/marker like this?:
-- or --
But what about necessary/non default values props?:
@property {String} name,shadow=true Human readable name@property {String} name,hidden Human readable name@property {Boolean} [published=null,shadow=true] Notification already published?@property {Boolean} published=null;shadow=true Notification already published?