Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Publish JS docs to spine.io #136

Merged
merged 19 commits into from
Mar 19, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .travis.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ env:
- PATH="$PATH:/usr/lib/dart/bin"
# Encrypted `NPM_TOKEN` variable to enable JS publishing.
- secure: kvg85udsH9a515YPHTh87LfyZhkL41HSvz4x+Q2OPoB9R3Irf+6HuaQCWSNNfPXIeqQefK+WuEG/kDBPOmm/JO7jVzMnt3p3mroDIYxod1uyea1sVlM+Jv23qe9J1txh0YsI9s0mrOJy/7X3IGBwpiGZGSM54J4l/mMheIG1GCmXp9abrkkkzzXKD8cn6p2P4/qoDF65SIe+GgHmhHJjxOCioIEwTlHd5UQxzkomCKMxPIzh15f4CppVbpVDSELcl8F9PLiS3zH3YOiBITMVA5IW6DHMbzipMQzBAzzAAFLnmkt30apqandsZzlIHJFKzNdlZrWcIrsiWTEqy9kYuvr6bszWtRjdDDu/GpaVytTlXquYE3u8vlpK5ngR0w2CTu0RQRPWli4zJ/bH81Ps9eNa8LVRTr3Og2ebUoibWk5YKksxSOedBUPu4HXs/v2CPxBfLwPnKd1OKgZK7O5/NtDHeoJLp+0jSXp6GpTybYY3WesB4YAz++DXGkcYha0isUvtM3LuDiHduFvWlB3JMgsq0MJ5WiWZMTDxJsXhK8tQvRfKxvkBiiigHQ5PvumOva/7xzy8GoZybQrh5m6j8SJcdNcbabLrkCl0yv0fMgrF5+aIhNMAU04FruSKH5k59SqKQwuyi7++Om8/NEuJfzZJ2YtF5AHwlIXv5gyygOk=
- FORMAL_GIT_HUB_PAGES_AUTHOR: "spine-developers@teamdev.com"

before_install:
- chmod +x gradlew
Expand All @@ -17,7 +18,8 @@ before_install:

# Decrypt and unarchive credentials for:
# - Maven repositories (cloudrepo.properties);
# - Google service account with Firebase admin privileges (spine-dev.json).
# - Google service account with Firebase admin privileges (spine-dev.json);
# - a private RSA key for publishing generated docs via GitHub pages.
- openssl aes-256-cbc -K $encrypted_676141212ed2_key -iv $encrypted_676141212ed2_iv -in credentials.tar.enc -out credentials.tar -d
- tar xvf credentials.tar
- mkdir ./integration-tests/test-app/src/main/resources/
Expand Down
6 changes: 6 additions & 0 deletions build.gradle
Original file line number Diff line number Diff line change
Expand Up @@ -243,6 +243,12 @@ subprojects {
}
}
}

final def projectsWithDocs = ['client-js', 'firebase-web', 'web']
if (projectsWithDocs.contains(project.name)) {
apply from: deps.scripts.updateGitHubPages
project.tasks.getByName('publish').dependsOn("$project.path:updateGitHubPages")
}
}

apply from: deps.scripts.jacoco
Expand Down
1 change: 1 addition & 0 deletions client-js/.npmrc
Original file line number Diff line number Diff line change
@@ -1 +1,2 @@
//registry.npmjs.org/:_authToken=${NPM_TOKEN}
package-lock=true
12 changes: 12 additions & 0 deletions client-js/build.gradle
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,8 @@
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/

import com.google.common.io.Files

apply from: "$rootDir/scripts/js.gradle"

apply plugin: 'com.google.protobuf'
Expand Down Expand Up @@ -60,3 +62,13 @@ sourceSets {
// Suppress building the JS project as a Java module.
project.compileJava.enabled = false
project.compileTestJava.enabled = false

final File jsDocDir = Files.createTempDir()

afterEvaluate {
generatedDocs += files(jsDocDir)
}

task jsDoc(type: Exec) {
commandLine 'jsdoc', '-d', jsDocDir.path, "$projectDir/main/*"
}
28 changes: 15 additions & 13 deletions client-js/main/client/actor-request-factory.js
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ const ENUM_VALUE_TYPE_URL = 'type.googleapis.com/google.protobuf.EnumValue';
export class Filters {

/**
* @typedef {string | number | boolean | Date | TypedMessage<T> | <T extends Message>} FieldValue
* @typedef {string | number | boolean | Date | TypedMessage<T> | Message} FieldValue
*
* Represents all types acceptable as a value for filtering.
*
Expand Down Expand Up @@ -382,11 +382,13 @@ const INVALID_FILTER_TYPE =
class AbstractTargetBuilder {

/**
* @param {!Class<T extends Message>} entity a Protobuf type of the target entities
* @param {!Class<Message>} entity a Protobuf type of the target entities
*/
constructor(entity) {
/**
* @type {Type} a type composed from the target entity class
* A type composed from the target entity class.
*
* @type {Type}
* @private
*/
this._type = Type.forClass(entity);
Expand Down Expand Up @@ -417,7 +419,7 @@ class AbstractTargetBuilder {
*
* If number IDs are passed they are assumed to be of `int64` Protobuf type.
*
* @param {!<T extends Message>[]|Number[]|String[]} ids an array with identifiers to query
* @param {!Message[]|!Number[]|!String[]} ids an array with identifiers to query
* @return {this} the current builder instance
* @throws if this method is executed more than once
* @throws if the provided IDs are not an instance of `Array`
Expand Down Expand Up @@ -554,7 +556,7 @@ class AbstractTargetBuilder {
* Checks that each provided item is an instance of the provided class. In case the check does
* not pass an error is thrown.
*
* @param {![]} items an array of objects that are expected to be of the provided type
* @param {!Array} items an array of objects that are expected to be of the provided type
* @param {!Object} cls a class each item is required to be instance of
* @param {!String} message an error message thrown on type mismatch
* @private
Expand All @@ -572,7 +574,7 @@ class AbstractTargetBuilder {
}

/**
* @param {![]} items an array of objects that are expected to be strings
* @param {!Array} items an array of objects that are expected to be strings
* @param {!String} message an error message thrown on type mismatch
* @private
*/
Expand All @@ -585,7 +587,7 @@ class AbstractTargetBuilder {
}

/**
* @param {![]} items an array of objects that are expected to be numbers
* @param {!Array} items an array of objects that are expected to be numbers
* @param {!String} message an error message thrown on type mismatch
* @private
*/
Expand All @@ -598,7 +600,7 @@ class AbstractTargetBuilder {
}

/**
* @param {![]} items an array of objects that are expected to be booleans
* @param {!Array} items an array of objects that are expected to be booleans
* @param {!String} message an error message thrown on type mismatch
* @private
*/
Expand All @@ -612,7 +614,7 @@ class AbstractTargetBuilder {

/**
* @param {!Object} cls a class tyo check items against
* @param {![]} items an array of objects that are expected to instances of class
* @param {!Array} items an array of objects that are expected to instances of class
* @param {!String} message an error message thrown on type mismatch
* @private
*/
Expand All @@ -635,7 +637,7 @@ class AbstractTargetBuilder {
class QueryBuilder extends AbstractTargetBuilder {

/**
* @param {!Class<T extends Message>} entity a Protobuf type of the query target entities
* @param {!Class<Message>} entity a Protobuf type of the query target entities
* @param {!QueryFactory} queryFactory
*/
constructor(entity, queryFactory) {
Expand Down Expand Up @@ -760,7 +762,7 @@ class QueryFactory {
/**
* Creates a new builder of `Query` instances of the provided type.
*
* @param {!Class<T extend Message>} entity a Protobuf type of the query target entities
* @param {!Class<Message>} entity a Protobuf type of the query target entities
* @return {QueryBuilder}
*/
select(entity) {
Expand Down Expand Up @@ -878,7 +880,7 @@ class CommandFactory {
class TopicBuilder extends AbstractTargetBuilder {

/**
* @param {!Class<T extends Message>} entity a Protobuf type of the subscription target entities
* @param {!Class<Message>} entity a Protobuf type of the subscription target entities
* @param {!TopicFactory} topicFactory
*/
constructor(entity, topicFactory) {
Expand Down Expand Up @@ -925,7 +927,7 @@ class TopicFactory {
/**
* Creates a new builder of `Topic` instances of the provided type.
*
* @param {!Class<T extend Message>} entity a Protobuf type of the subscription target entities
* @param {!Class<Message>} entity a Protobuf type of the subscription target entities
* @return {TopicBuilder}
*/
select(entity) {
Expand Down
12 changes: 6 additions & 6 deletions client-js/main/client/client.js
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ export class Client {
/**
* Creates a query request that allows to configure and post a new query.
*
* @param {!Class<? extends Message>} entityType a Protobuf type of the query target entities
* @param {!Class<Message>} entityType a Protobuf type of the query target entities
* @return {QueryRequest} the builder to construct and post a new query
*/
select(entityType) {
Expand All @@ -109,7 +109,7 @@ export class Client {
* Spine server fulfilling a returned promise with an array of received objects.
*
* @param {!spine.client.Query} query a query instance to be executed
* @return {Promise<<T extends Message>[]>} a promise to be fulfilled with a list of Protobuf
* @return {Promise<Message[]>} a promise to be fulfilled with a list of Protobuf
* messages of a given type or with an empty list if no entities matching given query
* were found; rejected with a `SpineError` if error occurs
*
Expand All @@ -124,7 +124,7 @@ export class Client {
* Spine server fulfilling a returned promise with an array of received objects.
*
* @param {!spine.client.Query} query a query instance to be executed
* @return {Promise<<T extends Message>[]>} a promise to be fulfilled with a list of Protobuf
* @return {Promise<Message[]>} a promise to be fulfilled with a list of Protobuf
* messages of a given type or with an empty list if no entities matching given query
* were found; rejected with a `SpineError` if error occurs;
*
Expand Down Expand Up @@ -170,7 +170,7 @@ export class Client {
/**
* Creates a subscription request that allows to configure and post a new entity subscription.
*
* @param {!Class<? extends Message>} entityType a Protobuf type of the target entities
* @param {!Class<Message>} entityType a Protobuf type of the target entities
* @return {SubscriptionRequest} the builder for the new entity subscription
*/
subscribeTo(entityType) {
Expand All @@ -184,7 +184,7 @@ export class Client {
* the topic that targets events.
*
* @param {!spine.client.Topic} topic a topic to subscribe to
* @return {Promise<EntitySubscriptionObject<T extends Message>>}
* @return {Promise<EntitySubscriptionObject<Message>>}
* the subscription object which exposes entity changes via its callbacks
*
* @template <T> a Protobuf type of entities being the target of a subscription
Expand All @@ -197,7 +197,7 @@ export class Client {
* Creates an event subscription request that allows to configure and post a new event
* subscription.
*
* @param {!Class<? extends Message>} eventType a Protobuf type of the target events
* @param {!Class<Message>} eventType a Protobuf type of the target events
* @return {EventSubscriptionRequest} the builder for the new event subscription
*/
subscribeToEvent(eventType) {
Expand Down
2 changes: 1 addition & 1 deletion client-js/main/client/command-request.js
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@ export class CommandRequest extends ClientRequest {
/**
* Adds the event type to the list of observed command handling results.
*
* @param {!Class<? extends Message>} eventType a type of the observed events
* @param {!Class<Message>} eventType a type of the observed events
* @param {!consumerCallback<EventSubscriptionCallbacks>} consumer
* a consumer of the `subscribe` and `unsubscribe` callbacks which are responsible for
* accepting the incoming events and cancelling the subscription respectively
Expand Down
6 changes: 5 additions & 1 deletion client-js/main/client/direct-client.js
Original file line number Diff line number Diff line change
Expand Up @@ -90,10 +90,14 @@ export class DirectClientFactory extends AbstractClientFactory {
class DirectQueryingClient extends QueryingClient {

/**
* An internal `DirectQueryingClient` constructor.
*
* Use `FirebaseClient#usingFirebase()` for instantiation.
*
* @param {!HttpEndpoint} endpoint the server endpoint to execute queries and commands
* @param {!ActorRequestFactory} actorRequestFactory a factory to instantiate the actor requests with
*
* @protected use `FirebaseClient#usingFirebase()` for instantiation
* @protected
*/
constructor(endpoint, actorRequestFactory) {
super(actorRequestFactory);
Expand Down
15 changes: 11 additions & 4 deletions client-js/main/client/filtering-request.js
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ import {ClientRequest} from "./client-request";
export class FilteringRequest extends ClientRequest {

/**
* @param {!Class<? extends Message>} targetType the target type of the request
* @param {!Class<Message>} targetType the target type of the request
* @param {!Client} client the client which initiated the request
* @param {!ActorRequestFactory} actorRequestFactory the request factory
*
Expand All @@ -45,7 +45,7 @@ export class FilteringRequest extends ClientRequest {
/**
* Adds filtering by IDs to the built request.
*
* @param ids {!<? extends Message>|Number|String|<? extends Message>[]|Number[]|String[]}
* @param ids {!Message|Number|String|Message[]|Number[]|String[]}
* the IDs of interest
* @return {this} self for method chaining
*/
Expand Down Expand Up @@ -87,7 +87,7 @@ export class FilteringRequest extends ClientRequest {
/**
* Returns the builder for messages that store request data.
*
* @return {AbstractTargetBuilder<T extends Message>} the builder instance
* @return {AbstractTargetBuilder<Message>} the builder instance
*
* @protected
*/
Expand All @@ -99,11 +99,18 @@ export class FilteringRequest extends ClientRequest {
return this._builderInstance;
}

/**
* @callback _NewBuilderFn
*
* @param {ActorRequestFactory}
* @return {AbstractTargetBuilder}
*/

/**
* Returns the function with which the {@link _builderInstance} can be created.
*
* @abstract
* @return {Function<ActorRequestFactory, B extends AbstractTargetBuilder>}
* @return {_NewBuilderFn}
*
* @protected
*/
Expand Down
12 changes: 10 additions & 2 deletions client-js/main/client/firebase-client.js
Original file line number Diff line number Diff line change
Expand Up @@ -132,11 +132,15 @@ class EventSubscription extends SpineSubscription {
class FirebaseQueryingClient extends QueryingClient {

/**
* A protected constructor for customization.
*
* Use `FirebaseClient#usingFirebase()` for instantiation
*
* @param {!HttpEndpoint} endpoint the server endpoint to execute queries and commands
* @param {!FirebaseDatabaseClient} firebaseDatabase the client to read the query results from
* @param {!ActorRequestFactory} actorRequestFactory a factory to instantiate the actor requests with
*
* @protected use `FirebaseClient#usingFirebase()` for instantiation
* @protected
*/
constructor(endpoint, firebaseDatabase, actorRequestFactory) {
super(actorRequestFactory);
Expand Down Expand Up @@ -166,6 +170,10 @@ const EVENT_TYPE_URL = 'type.spine.io/spine.core.Event';
class FirebaseSubscribingClient extends SubscribingClient {

/**
* A protected constructor for customization.
*
* Use `FirebaseClient#usingFirebase()` for instantiation.
*
* @param {!HttpEndpoint} endpoint
* the server endpoint to execute queries and commands
* @param {!FirebaseDatabaseClient} firebaseDatabase
Expand All @@ -175,7 +183,7 @@ class FirebaseSubscribingClient extends SubscribingClient {
* @param {!FirebaseSubscriptionService} subscriptionService
* a service handling the subscriptions
*
* @protected use `FirebaseClient#usingFirebase()` for instantiation
* @protected
*/
constructor(endpoint, firebaseDatabase, actorRequestFactory, subscriptionService) {
super(actorRequestFactory);
Expand Down
4 changes: 2 additions & 2 deletions client-js/main/client/query-request.js
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ import {FilteringRequest} from "./filtering-request";
export class QueryRequest extends FilteringRequest {

/**
* @param {!Class<T extends Message>} targetType the target type of entities
* @param {!Class<Message>} targetType the target type of entities
* @param {!Client} client the client which initiated the request
* @param {!ActorRequestFactory} actorRequestFactory the request factory
*/
Expand Down Expand Up @@ -97,7 +97,7 @@ export class QueryRequest extends FilteringRequest {
/**
* Runs the query and obtains the results.
*
* @return {Promise<<T extends Message>[]>} the asynchronously resolved query results
* @return {Promise<Message[]>} the asynchronously resolved query results
*/
run() {
const query = this.query();
Expand Down
4 changes: 2 additions & 2 deletions client-js/main/client/querying-client.js
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ export class QueryingClient {
/**
* Creates a new query request.
*
* @param {!Class<? extends Message>} entityType the target entity type
* @param {!Class<Message>} entityType the target entity type
* @param {!Client} client the client which initiated the request
* @return {QueryRequest} a new query request
*/
Expand All @@ -51,7 +51,7 @@ export class QueryingClient {
* Spine server fulfilling a returned promise with an array of received objects.
*
* @param {!spine.client.Query} query a query instance to be executed
* @return {Promise<<T extends Message>[]>} a promise to be fulfilled with a list of Protobuf
* @return {Promise<Message[]>} a promise to be fulfilled with a list of Protobuf
* messages of a given type or with an empty list if no entities matching given query
* were found; rejected with a `SpineError` if error occurs
*
Expand Down
6 changes: 3 additions & 3 deletions client-js/main/client/subscribing-client.js
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ export class SubscribingClient {
/**
* Creates a new subscription request.
*
* @param {!Class<? extends Message>} type the target entity type
* @param {!Class<Message>} type the target entity type
* @param {!Client} client the client that initiated the request
* @return {SubscriptionRequest} a new subscription request
*/
Expand All @@ -50,7 +50,7 @@ export class SubscribingClient {
* Subscribes to a given topic which targets an entity type.
*
* @param {!spine.client.Topic} topic a topic to subscribe to
* @return {Promise<EntitySubscriptionObject<T extends Message>>} a subscription object
* @return {Promise<EntitySubscriptionObject<Message>>} a subscription object
*
* @template <T> a Protobuf type of entities being the target of a subscription
*/
Expand All @@ -61,7 +61,7 @@ export class SubscribingClient {
/**
* Creates a new event subscription request.
*
* @param {!Class<? extends Message>} type the target event type
* @param {!Class<Message>} type the target event type
* @param {!Client} client the client that initiated the request
* @return {EventSubscriptionRequest} a new event subscription request
*/
Expand Down
Loading