From 06c90caf8a0deb31e4e49d66893e22914f39bcd3 Mon Sep 17 00:00:00 2001 From: Jesse Rosenberger Date: Mon, 29 Jan 2018 17:09:43 +0200 Subject: [PATCH 1/5] Attempt to generate "docs" during CircleCI tests. There have been a number of occasions where I have gone to bump the Meteor docs to the next major version, only to find that the docs deployment (which occurs in a separate repository; found at https://github.com/meteor/docs) fails due to code-refactoring which has taken place in its submodule (`code`, which is this Meteor codebase). In order to provide early warning when a JSDoc declaration in the Meteor code is going to (eventually) break the docs deployment which occurs in a separate repository (https://github.com/meteor/docs), this commit introduces a simple checkout and doc generation, in the same manner as the docs would in its own repository, within the CircleCI workflow. It's been configured in a way where it will not stop the normal Meteor test-suite from running, however it will show a separate indicator on GitHub pull-requests as to whether the generation of docs was successful or not. --- .circleci/config.yml | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/.circleci/config.yml b/.circleci/config.yml index 34c54df45d..1bae59a2ab 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -456,10 +456,50 @@ 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 run predeploy + npx hexo generate + workflows: version: 2 Build and Test: jobs: + - Docs - Get Ready - Group 0: requires: From ababb18aef6d75055f1f460ae4709c2ef26c4836 Mon Sep 17 00:00:00 2001 From: Jesse Rosenberger Date: Tue, 30 Jan 2018 19:20:20 +0200 Subject: [PATCH 2/5] Augment JSDoc declarations for Meteor.* connection convenience methods. The changes made in 8bbfd531c1cc9403e95aefb8c72cc0591c2ced3e prevent JSDoc (used to generate docs for https://docs.meteor.com via the https://github.com/meteor/docs repository) from associating the convenience methods which are exposed on the `Meteor` namespace (e.g. `Meteor.call`, `Meteor.apply`, `Meteor.reconnect,` etc.) as they are being identified as members of the `Connection` class. While this is techincally true, and all of these are also available on `Meteor.connection` (e.g. `Meteor.connection.status`), we have historically exposed them in the docs using their (preferred) `Meteor.*` aliases. Hopefully, this at least partially resolves https://github.com/meteor/docs/commit/8f7ceb5de5bf9bdd5935e3447164ce8f24cece7b. --- .../ddp-client/common/livedata_connection.js | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/packages/ddp-client/common/livedata_connection.js b/packages/ddp-client/common/livedata_connection.js index 781c7fa769..cec8200cfe 100644 --- a/packages/ddp-client/common/livedata_connection.js +++ b/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); From 4d861735c5c0ad43a21de0bc7d52c1a07be1ba62 Mon Sep 17 00:00:00 2001 From: Jesse Rosenberger Date: Tue, 30 Jan 2018 22:34:59 +0200 Subject: [PATCH 3/5] Export `check` as a named function declaration for JSDoc. The change made in a30f42c4acabb7591cdde61a1eaeac811610ba3e switched from CommonJS to ECMAScript export notation. It seems JSDoc isn't smart enough to make the same association as it did with the previous notation as it does for an anon. function expression `export`-ed as a `const`ant. We could annotate this with `@function check`, but it seems reasonable to just export a function declaration directly, which JSDoc will understand. This, along with ababb18aef6d75055f1f460ae4709c2ef26c4836, corrects the failure of docs generation originally discovered in: https://github.com/meteor/docs/commit/8f7ceb5de5bf9bdd5935e3447164ce8f24cece7b. Refs: https://github.com/meteor/meteor/pull/9593 --- packages/check/match.js | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/packages/check/match.js b/packages/check/match.js index 418b7f558f..a0faf2f123 100644 --- a/packages/check/match.js +++ b/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() From 46eaab39b6211a5ed56d544461cab1959ccb3c85 Mon Sep 17 00:00:00 2001 From: Jesse Rosenberger Date: Thu, 1 Feb 2018 11:59:27 +0200 Subject: [PATCH 4/5] Add misssing JSDoc declarations for Mongo.Collection#upsert. In the conversion to ECMAScript classes in https://github.com/meteor/meteor/commit/6fcf190bb489db19, it appears that JSDoc `@method`, `@instance` and `@memberof` declarations were already in place for the (outgoing) `Mongo.Collection.prototype.{foo}` expressions, with the exception of `upsert`. The omission caused docs generation failure with the new ES syntax since, presumably, it was less possible to be inferred from the `MCp*` notation. Additionally, this changes the casing of `@memberOf` to `@memberof`, mainly because: * The JSDocs use this notation. * The data JSON outputted by JSDoc lowercases property keys, including cases where `memberOf` was capitalized, making it less clear that there is a 1:1 mapping. * My editor refuses to syntax-highlight jsdoc declarations with [A-Z], possilby because of the above reasons. --- packages/mongo/collection.js | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/packages/mongo/collection.js b/packages/mongo/collection.js index 19cfb8ea8a..efad05a493 100644 --- a/packages/mongo/collection.js +++ b/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] From d6e1497350a143a27049d71c5d97bf26f5bde16f Mon Sep 17 00:00:00 2001 From: Jesse Rosenberger Date: Tue, 6 Feb 2018 16:54:04 +0200 Subject: [PATCH 5/5] Replace the Hexo test commands with new docs "npm test" script. As implemented now on the meteor/docs repository. Ref: https://github.com/meteor/docs/commit/af003a80bdf7f17f8ee0e95289add --- .circleci/config.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index 1bae59a2ab..129ed746c4 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -492,8 +492,7 @@ jobs: command: | cd ${CHECKOUT_METEOR_DOCS} npm install - npm run predeploy - npx hexo generate + npm test workflows: version: 2