Merge pull request #9593 from meteor/abernix/test-docs-with-meteor

Attempt to generate "docs" during CircleCI tests.

.circleci/config.yml

@@ -456,10 +456,49 @@ jobs:
       - store_artifacts:
           path: /tmp/memuse.txt
 
+  # Test the JSDoc declarations which live within this codebase against the
+  # Meteor Docs (https://github.com/meteor/docs) repository, where they'll
+  # eventually be consumed.  This test aims to provide an early warning of
+  # potentially breaking changes, so they aren't discovered when the docs are
+  # next updated, which generally occurs during major Meteor version releases
+  # (for example, 1.4 to 1.5, 1.5 to 1.6).
+  Docs:
+    docker:
+      # This Node version should match that in the meteor/docs CircleCI config.
+      - image: circleci/node:8
+    environment:
+      CHECKOUT_METEOR_DOCS: /home/circleci/test_docs
+    steps:
+      - run:
+          name: Cloning "meteor/docs" Repository's "master" branch
+          command: |
+            git clone https://github.com/meteor/docs.git ${CHECKOUT_METEOR_DOCS}
+      # The "docs" repository normally brings in the Meteor code as a Git
+      # submodule checked out into the "code" directory.  As the goal of this
+      # test is to run it against the _current_ repository's code, we'll move
+      # the "code" directory out of the way and move the checkout (of meteor)
+      # into that directory, rather than the default $CIRCLE_WORKING_DIRECTORY.
+      - checkout
+      - run:
+          name: Move Meteor checkout into docs repository's "code" directory
+          command: |
+            rmdir "${CHECKOUT_METEOR_DOCS}/code"
+            # $CIRCLE_WORKING_DIRECTORY uses a tilde, so expand it to $HOME.
+            mv "${CIRCLE_WORKING_DIRECTORY/#\~/$HOME}" \
+              "${CHECKOUT_METEOR_DOCS}/code"
+      # Run almost the same steps the meteor/docs repository runs, minus deploy.
+      - run:
+          name: Generating Meteor documentation for JSDoc testing
+          command: |
+            cd ${CHECKOUT_METEOR_DOCS}
+            npm install
+            npm test
+
 workflows:
   version: 2
   Build and Test:
     jobs:
+      - Docs
       - Get Ready
       - Group 0:
           requires:

packages/check/match.js

@@ -15,10 +15,9 @@ var hasOwn = Object.prototype.hasOwnProperty;
  * types and structure.
  * @locus Anywhere
  * @param {Any} value The value to check
- * @param {MatchPattern} pattern The pattern to match
- * `value` against
+ * @param {MatchPattern} pattern The pattern to match `value` against
  */
-export const check = function (value, pattern) {
+export function check(value, pattern) {
   // Record that check got called, if somebody cared.
   //
   // We use getOrNullIfOutsideFiber so that it's OK to call check()

packages/ddp-client/common/livedata_connection.js

@@ -330,6 +330,7 @@ export class Connection {
   /**
    * @memberOf Meteor
    * @importFromPackage meteor
+   * @alias Meteor.subscribe
    * @summary Subscribe to a record set.  Returns a handle that provides
    * `stop()` and `ready()` methods.
    * @locus Client
@@ -539,6 +540,7 @@ export class Connection {
   /**
    * @memberOf Meteor
    * @importFromPackage meteor
+   * @alias Meteor.call
    * @summary Invokes a method passing any number of arguments.
    * @locus Anywhere
    * @param {String} name Name of method to invoke
@@ -578,6 +580,7 @@ export class Connection {
   /**
    * @memberOf Meteor
    * @importFromPackage meteor
+   * @alias Meteor.apply
    * @summary Invoke a method passing an array of arguments.
    * @locus Anywhere
    * @param {String} name Name of method to invoke
@@ -888,10 +891,11 @@ export class Connection {
   }
 
   /**
-   * @summary Get the current connection status. A reactive data source.
-   * @locus Client
    * @memberOf Meteor
    * @importFromPackage meteor
+   * @alias Meteor.status
+   * @summary Get the current connection status. A reactive data source.
+   * @locus Client
    */
   status(...args) {
     return this._stream.status(...args);
@@ -901,19 +905,21 @@ export class Connection {
    * @summary Force an immediate reconnection attempt if the client is not connected to the server.
 
   This method does nothing if the client is already connected.
-   * @locus Client
    * @memberOf Meteor
    * @importFromPackage meteor
+   * @alias Meteor.reconnect
+   * @locus Client
    */
   reconnect(...args) {
     return this._stream.reconnect(...args);
   }
 
   /**
-   * @summary Disconnect the client from the server.
-   * @locus Client
    * @memberOf Meteor
    * @importFromPackage meteor
+   * @alias Meteor.disconnect
+   * @summary Disconnect the client from the server.
+   * @locus Client
    */
   disconnect(...args) {
     return this._stream.disconnect(...args);

packages/mongo/collection.js

@@ -305,7 +305,7 @@ Object.assign(Mongo.Collection.prototype, {
    * @summary Find the documents in a collection that match the selector.
    * @locus Anywhere
    * @method find
-   * @memberOf Mongo.Collection
+   * @memberof Mongo.Collection
    * @instance
    * @param {MongoSelector} [selector] A query describing the documents to find
    * @param {Object} [options]
@@ -336,7 +336,7 @@ Object.assign(Mongo.Collection.prototype, {
    * @summary Finds the first document that matches the selector, as ordered by sort and skip options. Returns `undefined` if no matching document is found.
    * @locus Anywhere
    * @method findOne
-   * @memberOf Mongo.Collection
+   * @memberof Mongo.Collection
    * @instance
    * @param {MongoSelector} [selector] A query describing the documents to find
    * @param {Object} [options]
@@ -441,7 +441,7 @@ Object.assign(Mongo.Collection.prototype, {
    * @summary Insert a document in the collection.  Returns its unique _id.
    * @locus Anywhere
    * @method  insert
-   * @memberOf Mongo.Collection
+   * @memberof Mongo.Collection
    * @instance
    * @param {Object} doc The document to insert. May not yet have an _id attribute, in which case Meteor will generate one for you.
    * @param {Function} [callback] Optional.  If present, called with an error object as the first argument and, if no error, the _id as the second.
@@ -527,7 +527,7 @@ Object.assign(Mongo.Collection.prototype, {
    * @summary Modify one or more documents in the collection. Returns the number of matched documents.
    * @locus Anywhere
    * @method update
-   * @memberOf Mongo.Collection
+   * @memberof Mongo.Collection
    * @instance
    * @param {MongoSelector} selector Specifies which documents to modify
    * @param {MongoModifier} modifier Specifies how to modify the documents
@@ -592,7 +592,7 @@ Object.assign(Mongo.Collection.prototype, {
    * @summary Remove documents from the collection
    * @locus Anywhere
    * @method remove
-   * @memberOf Mongo.Collection
+   * @memberof Mongo.Collection
    * @instance
    * @param {MongoSelector} selector Specifies which documents to remove
    * @param {Function} [callback] Optional.  If present, called with an error object as its argument.
@@ -632,6 +632,9 @@ Object.assign(Mongo.Collection.prototype, {
   /**
    * @summary Modify one or more documents in the collection, or insert one if no matching documents were found. Returns an object with keys `numberAffected` (the number of documents modified)  and `insertedId` (the unique _id of the document that was inserted, if any).
    * @locus Anywhere
+   * @method upsert
+   * @memberof Mongo.Collection
+   * @instance
    * @param {MongoSelector} selector Specifies which documents to modify
    * @param {MongoModifier} modifier Specifies how to modify the documents
    * @param {Object} [options]