From ef022c83266e9fe31cef6f41c119c96f0b145b82 Mon Sep 17 00:00:00 2001
From: Svornost <11434-svornost@users.noreply.gitgud.io>
Date: Mon, 27 Apr 2020 17:21:52 -0700
Subject: [PATCH] Improve JSDoc in the event system. Fix a few little bugs.
---
src/events/001-base/baseEvent.js | 20 ++++++++++++++++----
src/events/RESS/hotPC.js | 2 +-
src/events/RESS/moistPussy.js | 3 +--
src/events/eventUtils.js | 31 +++++++++++++++++++------------
src/js/itemAvailability.js | 4 ++--
5 files changed, 39 insertions(+), 21 deletions(-)
diff --git a/src/events/001-base/baseEvent.js b/src/events/001-base/baseEvent.js
index bd14a10f55d..9e8167176cf 100644
--- a/src/events/001-base/baseEvent.js
+++ b/src/events/001-base/baseEvent.js
@@ -2,7 +2,10 @@
App.Events.BaseEvent = class BaseEvent {
/** build a new event
* parameters are necessary for serialization (so that saving with the event active will work correctly) and should not normally be used directly
- * child classes will inherit this implementation automatically, and should not normally need their own constructor implementation */
+ * child classes will inherit this implementation automatically, and should not normally need their own constructor implementation
+ * @param {Array<number>} [actors]
+ * @param {object} [params]
+ */
constructor(actors, params) {
/** @member {Array<number>} actors - a list of IDs for the actors participating in this event. */
this.actors = actors || [];
@@ -10,18 +13,27 @@ App.Events.BaseEvent = class BaseEvent {
this.params = params || {};
}
- /** generate an array of zero or more predicates which must all be true in order for the event to be valid.
+ /** Event predicates determine whether the event will occur or not.
+ * @callback eventPredicate
+ * @returns {boolean}
+ */
+ /** generate an array of zero or more predicates which must all return true in order for the event to be valid.
* lambda predicates may add properties to {@link App.Events.BaseEvent#params the params member} in order to pass information on to the event.
* child classes should implement this.
- * @returns {Array<Function>}
+ * @returns {Array<eventPredicate>}
*/
eventPrerequisites() {
return [];
}
+ /** Actor predicates determine whether an actor is qualified for an event or not.
+ * @callback actorPredicate
+ * @param {App.Entity.SlaveState} slave
+ * @returns {boolean}
+ */
/** generate an array of zero or more arrays, each corresponding to an actor in the event, which contain zero or more predicates which must be satisfied by the actor.
* child classes should implement this.
- * @returns {Array<Array<Function>>}
+ * @returns {Array<Array<actorPredicate>>}
*/
actorPrerequisites() {
return [];
diff --git a/src/events/RESS/hotPC.js b/src/events/RESS/hotPC.js
index ebd65124c53..f31d4645ba7 100644
--- a/src/events/RESS/hotPC.js
+++ b/src/events/RESS/hotPC.js
@@ -169,7 +169,7 @@ App.Events.RESSHotPC = class RESSHotPC extends App.Events.BaseEvent {
function fuck() {
t = [];
- if (PC.title === 0 || $PC.boobs >= 300 || $PC.belly >= 1500) {
+ if (PC.title === 0 || PC.boobs >= 300 || PC.belly >= 1500) {
t.push("Despite your feminine appearance, you have capable hands.");
} else {
t.push("You have strong hands to go with your masculine appeal.");
diff --git a/src/events/RESS/moistPussy.js b/src/events/RESS/moistPussy.js
index e800ec8eda6..dada74e0c7e 100644
--- a/src/events/RESS/moistPussy.js
+++ b/src/events/RESS/moistPussy.js
@@ -2,12 +2,11 @@ App.Events.RESSMoistPussy = class RESSMoistPussy extends App.Events.BaseEvent {
eventPrerequisites() {
return []; // always valid if sufficient actors can be cast successfully
}
- /** @type {App.Entity.SlaveState} */
actorPrerequisites() {
return [
[ // single event slave
- s.assignment !== "work as a servant",
+ s => s.assignment !== "work as a servant",
s => s.devotion > 20,
s => s.vaginaLube > 1,
hasAnyArms,
diff --git a/src/events/eventUtils.js b/src/events/eventUtils.js
index e24d5a99769..2faec70e59e 100644
--- a/src/events/eventUtils.js
+++ b/src/events/eventUtils.js
@@ -1,7 +1,7 @@
/** draw event art, with the option to dress the slave in a particular way
- * @param {HTMLElement} node - DOM node to attach art to
+ * @param {Node} node - DOM node to attach art to
* @param {App.Entity.SlaveState|Array<App.Entity.SlaveState>} slaves - one or several slaves to draw art for
- * @param {[string]} clothesMode - if the slaves' clothing should be overridden, what should they be wearing?
+ * @param {string} [clothesMode] - if the slaves' clothing should be overridden, what should they be wearing?
*/
App.Events.drawEventArt = function(node, slaves, clothesMode) {
// do nothing if the player doesn't want images
@@ -59,8 +59,8 @@ App.Events.drawEventArt = function(node, slaves, clothesMode) {
};
/** intelligently adds spaces to an array of mixed strings and DOM nodes, merging consecutive strings in the process
- * @param {Array<string|HTMLElement>} sentences
- * @returns {Array<string|HTMLElement>}
+ * @param {Array<string|HTMLElement|DocumentFragment>} sentences
+ * @returns {Array<string|HTMLElement|DocumentFragment>}
*/
App.Events.spaceSentences = function(sentences) {
if (sentences.length <= 1) {
@@ -89,20 +89,24 @@ App.Events.spaceSentences = function(sentences) {
};
/** assemble a DOM paragraph from an array of DOM nodes, sentences or sentence fragments (which may contain HTML)
- * @param {HTMLElement} node
- * @param {Array<string|HTMLElement>} sentences
+ * @param {Node} node
+ * @param {Array<string|HTMLElement|DocumentFragment>} sentences
*/
App.Events.addParagraph = function(node, sentences) {
let para = document.createElement("p");
- $(para).append(App.Events.spaceSentences(sentences));
+ $(para).append(...App.Events.spaceSentences(sentences));
node.appendChild(para);
};
+/** result handler callback - process the result and return an array of mixed strings and DOM nodes
+ * @callback resultHandler
+ * @returns {Array<string|HTMLElement|DocumentFragment>}
+ */
/** a response to an event, and its result */
App.Events.Result = class {
- /** @param {[string]} text - the link text for the response
- * @param {[Function]} handler - the function to call to generate the result when the link is clicked
- * @param {[string]} note - a note to provide alongside the link (for example, a cost or virginity loss warning)
+ /** @param {string} [text] - the link text for the response
+ * @param {resultHandler} [handler] - the function to call to generate the result when the link is clicked
+ * @param {string} [note] - a note to provide alongside the link (for example, a cost or virginity loss warning)
* To mark an option as disabled, construct the result with only the note.
*/
constructor(text, handler, note) {
@@ -111,9 +115,12 @@ App.Events.Result = class {
this.note = note;
}
+ /** call the result handler, replacing the contents of the given span ID
+ * @param {string} resultSpanID
+ */
handle(resultSpanID) {
let frag = document.createDocumentFragment();
- $(frag).append(App.Events.spaceSentences(this.handler()));
+ $(frag).append(...App.Events.spaceSentences(this.handler()));
App.UI.DOM.replace(`#${resultSpanID}`, frag);
}
@@ -139,7 +146,7 @@ App.Events.Result = class {
};
/** add a list of results for an event
- * @param {HTMLElement} node
+ * @param {Node} node
* @param {Array<App.Events.Result>} results
* @param {string} [elementID="result"]
*/
diff --git a/src/js/itemAvailability.js b/src/js/itemAvailability.js
index 6897171593e..436f5c09235 100644
--- a/src/js/itemAvailability.js
+++ b/src/js/itemAvailability.js
@@ -7,8 +7,8 @@ globalThis.isItemAccessible = (function() {
/**
* Checks whether an item is accessible
* @param {string} string Name of wearable item
- * @param {string} category that item is in clothing, collar, etc
- * @param {App.Entity.SlaveState} slave
+ * @param {string} [category="clothing"] that item is in clothing, collar, etc
+ * @param {App.Entity.SlaveState} [slave]
* @returns {boolean|string} Returns true if item is accessible, and false if it is not. If the slave param is set, it may sometimes return a string instead of false, explaining why the item can't be used with that slave.
*/
function entry(string, category = "clothing", slave) {
--
GitLab