Merge pull request #12072 from hasezoey/receiverRefactor

Refactor all `@receiver` tags to proper jsdoc tags
Automattic · Jul 8, 2022 · 6b86a9b · 6b86a9b
2 parents cfdb1d8 + d4e3522
commit 6b86a9b
Show file tree

Hide file tree

Showing 8 changed files with 33 additions and 26 deletions.
diff --git a/docs/source/api.js b/docs/source/api.js
@@ -126,26 +126,29 @@ function parse() {
         ctx.constructorWasUndefined = true;
       }
 
+      // helper function to keep translating array types to string consistent
+      function convertTypesToString(types) {
+        return Array.isArray(types) ? types.join('|') : types
+      }
+
       for (const tag of prop.tags) {
         switch (tag.type) {
           case 'receiver':
-            ctx.constructor = tag.string;
+            console.warn(`Found "@receiver" tag in ${ctx.constructor} ${ctx.name}`);
             break;
           case 'property':
             ctx.type = 'property';
 
-            // somewhere since 6.0 the "string" property came back, which was gone with 4.5
-            let str = tag.string;
-
-            const match = str.match(/^{\w+}/);
-            if (match != null) {
-              ctx.type = match[0].substring(1, match[0].length - 1);
-              str = str.replace(/^{\w+}\s*/, '');
+            // using "name" over "string" because "string" also contains the type and maybe other stuff
+            ctx.name = tag.name;
+            // only assign "type" if there are types
+            if (tag.types.length > 0) {
+              ctx.type = convertTypesToString(tag.types);
             }
-            ctx.name = str;
+
             break;
           case 'type':
-            ctx.type = Array.isArray(tag.types) ? tag.types.join('|') : tag.types;
+            ctx.type = convertTypesToString(tag.types);
             break;
           case 'static':
             ctx.type = 'property';
@@ -184,7 +187,7 @@ function parse() {
               tag.types.push('null');
             }
             if (tag.types) {
-              tag.types = tag.types.join('|');
+              tag.types = convertTypesToString(tag.types);
             }
             ctx[tag.type].push(tag);
             if (tag.name != null && tag.name.startsWith('[') && tag.name.endsWith(']') && tag.name.includes('.')) {

diff --git a/lib/error/messages.js b/lib/error/messages.js
@@ -17,7 +17,7 @@
  * Click the "show code" link below to see all defaults.
  *
  * @static
- * @receiver MongooseError
+ * @memberOf MongooseError
  * @api public
  */
 

diff --git a/lib/model.js b/lib/model.js
@@ -1822,7 +1822,7 @@ function _ensureIndexes(model, options, callback) {
  * Schema the model uses.
  *
  * @property schema
- * @receiver Model
+ * @static
  * @api public
  * @memberOf Model
  */

diff --git a/lib/query.js b/lib/query.js
@@ -170,7 +170,7 @@ Query.base = mquery.prototype;
  * @default true
  * @property use$geoWithin
  * @memberOf Query
- * @receiver Query
+ * @static
  * @api public
  */
 
@@ -1847,7 +1847,7 @@ Query.prototype.setUpdate = function(val) {
  * @method _fieldsForExec
  * @return {Object}
  * @api private
- * @receiver Query
+ * @memberOf Query
  */
 
 Query.prototype._fieldsForExec = function() {
@@ -1859,8 +1859,9 @@ Query.prototype._fieldsForExec = function() {
  * Return an update document with corrected `$set` operations.
  *
  * @method _updateForExec
+ * @return {Object}
  * @api private
- * @receiver Query
+ * @memberOf Query
  */
 
 Query.prototype._updateForExec = function() {
@@ -1907,10 +1908,12 @@ Query.prototype._updateForExec = function() {
 /**
  * Makes sure _path is set.
  *
+ * This method is inherited by `mquery`
+ *
  * @method _ensurePath
  * @param {String} method
  * @api private
- * @receiver Query
+ * @memberOf Query
  */
 
 /**

diff --git a/lib/schema.js b/lib/schema.js
@@ -1870,16 +1870,17 @@ Schema.prototype.get = function(key) {
   return this.options[key];
 };
 
+const indexTypes = '2d 2dsphere hashed text'.split(' ');
+
 /**
  * The allowed index types
  *
- * @receiver Schema
+ * @property {String[]} indexTypes
+ * @memberOf Schema
  * @static
  * @api public
  */
 
-const indexTypes = '2d 2dsphere hashed text'.split(' ');
-
 Object.defineProperty(Schema, 'indexTypes', {
   get: function() {
     return indexTypes;

diff --git a/lib/schematype.js b/lib/schematype.js
@@ -206,7 +206,7 @@ SchemaType.prototype.splitPath = function() {
  * @param {Function|false} caster Function that casts arbitrary values to this type, or throws an error if casting failed
  * @return {Function}
  * @static
- * @receiver SchemaType
+ * @memberOf SchemaType
  * @function cast
  * @api public
  */
@@ -280,7 +280,7 @@ SchemaType.prototype.cast = function cast() {
  * @param {Any} value The value of the option you'd like to set.
  * @return {void}
  * @static
- * @receiver SchemaType
+ * @memberOf SchemaType
  * @function set
  * @api public
  */
@@ -303,7 +303,7 @@ SchemaType.set = function set(option, value) {
  * @param {Function} getter
  * @return {this}
  * @static
- * @receiver SchemaType
+ * @memberOf SchemaType
  * @function get
  * @api public
  */
@@ -1634,7 +1634,7 @@ SchemaType.prototype._castForQuery = function(val) {
  * @param {Function} fn
  * @return {Function}
  * @static
- * @receiver SchemaType
+ * @memberOf SchemaType
  * @function checkRequired
  * @api public
  */

diff --git a/lib/types/DocumentArray/methods/index.js b/lib/types/DocumentArray/methods/index.js
@@ -35,7 +35,7 @@ const methods = {
    *
    * @method _cast
    * @api private
-   * @receiver MongooseDocumentArray
+   * @memberOf MongooseDocumentArray
    */
 
   _cast(value, index) {

diff --git a/lib/types/subdocument.js b/lib/types/subdocument.js
@@ -188,7 +188,7 @@ Subdocument.prototype.isModified = function(paths, modifiedPaths) {
  * @param {String} path the field to mark as valid
  * @api private
  * @method $markValid
- * @receiver Subdocument
+ * @memberOf Subdocument
  */
 
 Subdocument.prototype.$markValid = function(path) {