From 8fc379eeb1974bb43053b1087cbe7a71ab499d34 Mon Sep 17 00:00:00 2001 From: Song Wang Date: Fri, 2 Jun 2017 14:45:33 -0700 Subject: [PATCH 01/17] Add dummy js files for datastore gapic/proto documentation --- packages/datastore/src/doc_datastore.js | 411 +++++++++++++++ packages/datastore/src/doc_entity.js | 250 +++++++++ .../src/doc_google_protobuf_wrappers.js | 128 +++++ packages/datastore/src/doc_query.js | 489 ++++++++++++++++++ 4 files changed, 1278 insertions(+) create mode 100644 packages/datastore/src/doc_datastore.js create mode 100644 packages/datastore/src/doc_entity.js create mode 100644 packages/datastore/src/doc_google_protobuf_wrappers.js create mode 100644 packages/datastore/src/doc_query.js diff --git a/packages/datastore/src/doc_datastore.js b/packages/datastore/src/doc_datastore.js new file mode 100644 index 00000000000..3ff2ec875f0 --- /dev/null +++ b/packages/datastore/src/doc_datastore.js @@ -0,0 +1,411 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * The request for {@link Datastore.Lookup}. + * + * @property {string} projectId + * The ID of the project against which to make the request. + * + * @property {Object} readOptions + * The options for this lookup request. + * + * This object should have the same structure as [ReadOptions]{@link ReadOptions} + * + * @property {Object[]} keys + * Keys of entities to look up. + * + * This object should have the same structure as [Key]{@link Key} + * + * @class + * @see [google.datastore.v1.LookupRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + */ +var LookupRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The response for {@link Datastore.Lookup}. + * + * @property {Object[]} found + * Entities found as `ResultType.FULL` entities. The order of results in this + * field is undefined and has no relation to the order of the keys in the + * input. + * + * This object should have the same structure as [EntityResult]{@link EntityResult} + * + * @property {Object[]} missing + * Entities not found as `ResultType.KEY_ONLY` entities. The order of results + * in this field is undefined and has no relation to the order of the keys + * in the input. + * + * This object should have the same structure as [EntityResult]{@link EntityResult} + * + * @property {Object[]} deferred + * A list of keys that were not looked up due to resource constraints. The + * order of results in this field is undefined and has no relation to the + * order of the keys in the input. + * + * This object should have the same structure as [Key]{@link Key} + * + * @class + * @see [google.datastore.v1.LookupResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + */ +var LookupResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for {@link Datastore.RunQuery}. + * + * @property {string} projectId + * The ID of the project against which to make the request. + * + * @property {Object} partitionId + * Entities are partitioned into subsets, identified by a partition ID. + * Queries are scoped to a single partition. + * This partition ID is normalized with the standard default context + * partition ID. + * + * This object should have the same structure as [PartitionId]{@link PartitionId} + * + * @property {Object} readOptions + * The options for this query. + * + * This object should have the same structure as [ReadOptions]{@link ReadOptions} + * + * @property {Object} query + * The query to run. + * + * This object should have the same structure as [Query]{@link Query} + * + * @property {Object} gqlQuery + * The GQL query to run. + * + * This object should have the same structure as [GqlQuery]{@link GqlQuery} + * + * @class + * @see [google.datastore.v1.RunQueryRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + */ +var RunQueryRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The response for {@link Datastore.RunQuery}. + * + * @property {Object} batch + * A batch of query results (always present). + * + * This object should have the same structure as [QueryResultBatch]{@link QueryResultBatch} + * + * @property {Object} query + * The parsed form of the `GqlQuery` from the request, if it was set. + * + * This object should have the same structure as [Query]{@link Query} + * + * @class + * @see [google.datastore.v1.RunQueryResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + */ +var RunQueryResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for {@link Datastore.BeginTransaction}. + * + * @property {string} projectId + * The ID of the project against which to make the request. + * + * @class + * @see [google.datastore.v1.BeginTransactionRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + */ +var BeginTransactionRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The response for {@link Datastore.BeginTransaction}. + * + * @property {string} transaction + * The transaction identifier (always present). + * + * @class + * @see [google.datastore.v1.BeginTransactionResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + */ +var BeginTransactionResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for {@link Datastore.Rollback}. + * + * @property {string} projectId + * The ID of the project against which to make the request. + * + * @property {string} transaction + * The transaction identifier, returned by a call to + * {@link Datastore.BeginTransaction}. + * + * @class + * @see [google.datastore.v1.RollbackRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + */ +var RollbackRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The response for {@link Datastore.Rollback}. + * (an empty message). + * @class + * @see [google.datastore.v1.RollbackResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + */ +var RollbackResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for {@link Datastore.Commit}. + * + * @property {string} projectId + * The ID of the project against which to make the request. + * + * @property {number} mode + * The type of commit to perform. Defaults to `TRANSACTIONAL`. + * + * The number should be among the values of [Mode]{@link Mode} + * + * @property {string} transaction + * The identifier of the transaction associated with the commit. A + * transaction identifier is returned by a call to + * {@link Datastore.BeginTransaction}. + * + * @property {Object[]} mutations + * The mutations to perform. + * + * When mode is `TRANSACTIONAL`, mutations affecting a single entity are + * applied in order. The following sequences of mutations affecting a single + * entity are not permitted in a single `Commit` request: + * + * - `insert` followed by `insert` + * - `update` followed by `insert` + * - `upsert` followed by `insert` + * - `delete` followed by `update` + * + * When mode is `NON_TRANSACTIONAL`, no two mutations may affect a single + * entity. + * + * This object should have the same structure as [Mutation]{@link Mutation} + * + * @class + * @see [google.datastore.v1.CommitRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + */ +var CommitRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * The modes available for commits. + * + * @enum {number} + */ + Mode: { + + /** + * Unspecified. This value must not be used. + */ + MODE_UNSPECIFIED: 0, + + /** + * Transactional: The mutations are either all applied, or none are applied. + * Learn about transactions [here](https://cloud.google.com/datastore/docs/concepts/transactions). + */ + TRANSACTIONAL: 1, + + /** + * Non-transactional: The mutations may not apply as all or none. + */ + NON_TRANSACTIONAL: 2 + } +}; + +/** + * The response for {@link Datastore.Commit}. + * + * @property {Object[]} mutationResults + * The result of performing the mutations. + * The i-th mutation result corresponds to the i-th mutation in the request. + * + * This object should have the same structure as [MutationResult]{@link MutationResult} + * + * @property {number} indexUpdates + * The number of index entries updated during the commit, or zero if none were + * updated. + * + * @class + * @see [google.datastore.v1.CommitResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + */ +var CommitResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for {@link Datastore.AllocateIds}. + * + * @property {string} projectId + * The ID of the project against which to make the request. + * + * @property {Object[]} keys + * A list of keys with incomplete key paths for which to allocate IDs. + * No key may be reserved/read-only. + * + * This object should have the same structure as [Key]{@link Key} + * + * @class + * @see [google.datastore.v1.AllocateIdsRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + */ +var AllocateIdsRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The response for {@link Datastore.AllocateIds}. + * + * @property {Object[]} keys + * The keys specified in the request (in the same order), each with + * its key path completed with a newly allocated ID. + * + * This object should have the same structure as [Key]{@link Key} + * + * @class + * @see [google.datastore.v1.AllocateIdsResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + */ +var AllocateIdsResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A mutation to apply to an entity. + * + * @property {Object} insert + * The entity to insert. The entity must not already exist. + * The entity key's final path element may be incomplete. + * + * This object should have the same structure as [Entity]{@link Entity} + * + * @property {Object} update + * The entity to update. The entity must already exist. + * Must have a complete key path. + * + * This object should have the same structure as [Entity]{@link Entity} + * + * @property {Object} upsert + * The entity to upsert. The entity may or may not already exist. + * The entity key's final path element may be incomplete. + * + * This object should have the same structure as [Entity]{@link Entity} + * + * @property {Object} delete + * The key of the entity to delete. The entity may or may not already exist. + * Must have a complete key path and must not be reserved/read-only. + * + * This object should have the same structure as [Key]{@link Key} + * + * @property {number} baseVersion + * The version of the entity that this mutation is being applied to. If this + * does not match the current version on the server, the mutation conflicts. + * + * @class + * @see [google.datastore.v1.Mutation definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + */ +var Mutation = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The result of applying a mutation. + * + * @property {Object} key + * The automatically allocated key. + * Set only when the mutation allocated a key. + * + * This object should have the same structure as [Key]{@link Key} + * + * @property {number} version + * The version of the entity on the server after processing the mutation. If + * the mutation doesn't change anything on the server, then the version will + * be the version of the current entity or, if no entity is present, a version + * that is strictly greater than the version of any previous entity and less + * than the version of any possible future entity. + * + * @property {boolean} conflictDetected + * Whether a conflict was detected for this mutation. Always false when a + * conflict detection strategy field is not set in the mutation. + * + * @class + * @see [google.datastore.v1.MutationResult definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + */ +var MutationResult = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The options shared by read requests. + * + * @property {number} readConsistency + * The non-transactional read consistency to use. + * Cannot be set to `STRONG` for global queries. + * + * The number should be among the values of [ReadConsistency]{@link ReadConsistency} + * + * @property {string} transaction + * The identifier of the transaction in which to read. A + * transaction identifier is returned by a call to + * {@link Datastore.BeginTransaction}. + * + * @class + * @see [google.datastore.v1.ReadOptions definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + */ +var ReadOptions = { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * The possible values for read consistencies. + * + * @enum {number} + */ + ReadConsistency: { + + /** + * Unspecified. This value must not be used. + */ + READ_CONSISTENCY_UNSPECIFIED: 0, + + /** + * Strong consistency. + */ + STRONG: 1, + + /** + * Eventual consistency. + */ + EVENTUAL: 2 + } +}; \ No newline at end of file diff --git a/packages/datastore/src/doc_entity.js b/packages/datastore/src/doc_entity.js new file mode 100644 index 00000000000..33ae665f9da --- /dev/null +++ b/packages/datastore/src/doc_entity.js @@ -0,0 +1,250 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * A partition ID identifies a grouping of entities. The grouping is always + * by project and namespace, however the namespace ID may be empty. + * + * A partition ID contains several dimensions: + * project ID and namespace ID. + * + * Partition dimensions: + * + * - May be `""`. + * - Must be valid UTF-8 bytes. + * - Must have values that match regex `[A-Za-z\d\.\-_]{1,100}` + * If the value of any dimension matches regex `__.*__`, the partition is + * reserved/read-only. + * A reserved/read-only partition ID is forbidden in certain documented + * contexts. + * + * Foreign partition IDs (in which the project ID does + * not match the context project ID ) are discouraged. + * Reads and writes of foreign partition IDs may fail if the project is not in an active state. + * + * @property {string} projectId + * The ID of the project to which the entities belong. + * + * @property {string} namespaceId + * If not empty, the ID of the namespace to which the entities belong. + * + * @class + * @see [google.datastore.v1.PartitionId definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/entity.proto} + */ +var PartitionId = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A unique identifier for an entity. + * If a key's partition ID or any of its path kinds or names are + * reserved/read-only, the key is reserved/read-only. + * A reserved/read-only key is forbidden in certain documented contexts. + * + * @property {Object} partitionId + * Entities are partitioned into subsets, currently identified by a project + * ID and namespace ID. + * Queries are scoped to a single partition. + * + * This object should have the same structure as [PartitionId]{@link PartitionId} + * + * @property {Object[]} path + * The entity path. + * An entity path consists of one or more elements composed of a kind and a + * string or numerical identifier, which identify entities. The first + * element identifies a _root entity_, the second element identifies + * a _child_ of the root entity, the third element identifies a child of the + * second entity, and so forth. The entities identified by all prefixes of + * the path are called the element's _ancestors_. + * + * An entity path is always fully complete: *all* of the entity's ancestors + * are required to be in the path along with the entity identifier itself. + * The only exception is that in some documented cases, the identifier in the + * last path element (for the entity) itself may be omitted. For example, + * the last path element of the key of `Mutation.insert` may have no + * identifier. + * + * A path can never be empty, and a path can have at most 100 elements. + * + * This object should have the same structure as [PathElement]{@link PathElement} + * + * @class + * @see [google.datastore.v1.Key definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/entity.proto} + */ +var Key = { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * A (kind, ID/name) pair used to construct a key path. + * + * If either name or ID is set, the element is complete. + * If neither is set, the element is incomplete. + * + * @property {string} kind + * The kind of the entity. + * A kind matching regex `__.*__` is reserved/read-only. + * A kind must not contain more than 1500 bytes when UTF-8 encoded. + * Cannot be `""`. + * + * @property {number} id + * The auto-allocated ID of the entity. + * Never equal to zero. Values less than zero are discouraged and may not + * be supported in the future. + * + * @property {string} name + * The name of the entity. + * A name matching regex `__.*__` is reserved/read-only. + * A name must not be more than 1500 bytes when UTF-8 encoded. + * Cannot be `""`. + * + * @class + * @see [google.datastore.v1.Key.PathElement definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/entity.proto} + */ + PathElement: { + // This is for documentation. Actual contents will be loaded by gRPC. + } +}; + +/** + * An array value. + * + * @property {Object[]} values + * Values in the array. + * The order of this array may not be preserved if it contains a mix of + * indexed and unindexed values. + * + * This object should have the same structure as [Value]{@link Value} + * + * @class + * @see [google.datastore.v1.ArrayValue definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/entity.proto} + */ +var ArrayValue = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A message that can hold any of the supported value types and associated + * metadata. + * + * @property {number} nullValue + * A null value. + * + * The number should be among the values of [google.protobuf.NullValue]{@link external:"google.protobuf.NullValue"} + * + * @property {boolean} booleanValue + * A boolean value. + * + * @property {number} integerValue + * An integer value. + * + * @property {number} doubleValue + * A double value. + * + * @property {Object} timestampValue + * A timestamp value. + * When stored in the Datastore, precise only to microseconds; + * any additional precision is rounded down. + * + * This object should have the same structure as [google.protobuf.Timestamp]{@link external:"google.protobuf.Timestamp"} + * + * @property {Object} keyValue + * A key value. + * + * This object should have the same structure as [Key]{@link Key} + * + * @property {string} stringValue + * A UTF-8 encoded string value. + * When `exclude_from_indexes` is false (it is indexed) , may have at most 1500 bytes. + * Otherwise, may be set to at least 1,000,000 bytes. + * + * @property {string} blobValue + * A blob value. + * May have at most 1,000,000 bytes. + * When `exclude_from_indexes` is false, may have at most 1500 bytes. + * In JSON requests, must be base64-encoded. + * + * @property {Object} geoPointValue + * A geo point value representing a point on the surface of Earth. + * + * This object should have the same structure as [google.type.LatLng]{@link external:"google.type.LatLng"} + * + * @property {Object} entityValue + * An entity value. + * + * - May have no key. + * - May have a key with an incomplete key path. + * - May have a reserved/read-only key. + * + * This object should have the same structure as [Entity]{@link Entity} + * + * @property {Object} arrayValue + * An array value. + * Cannot contain another array value. + * A `Value` instance that sets field `array_value` must not set fields + * `meaning` or `exclude_from_indexes`. + * + * This object should have the same structure as [ArrayValue]{@link ArrayValue} + * + * @property {number} meaning + * The `meaning` field should only be populated for backwards compatibility. + * + * @property {boolean} excludeFromIndexes + * If the value should be excluded from all indexes including those defined + * explicitly. + * + * @class + * @see [google.datastore.v1.Value definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/entity.proto} + */ +var Value = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A Datastore data object. + * + * An entity is limited to 1 megabyte when stored. That _roughly_ + * corresponds to a limit of 1 megabyte for the serialized form of this + * message. + * + * @property {Object} key + * The entity's key. + * + * An entity must have a key, unless otherwise documented (for example, + * an entity in `Value.entity_value` may have no key). + * An entity's kind is its key path's last element's kind, + * or null if it has no key. + * + * This object should have the same structure as [Key]{@link Key} + * + * @property {Object.} properties + * The entity's properties. + * The map's keys are property names. + * A property name matching regex `__.*__` is reserved. + * A reserved property name is forbidden in certain documented contexts. + * The name must not contain more than 500 characters. + * The name cannot be `""`. + * + * @class + * @see [google.datastore.v1.Entity definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/entity.proto} + */ +var Entity = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; \ No newline at end of file diff --git a/packages/datastore/src/doc_google_protobuf_wrappers.js b/packages/datastore/src/doc_google_protobuf_wrappers.js new file mode 100644 index 00000000000..46a5e3e2213 --- /dev/null +++ b/packages/datastore/src/doc_google_protobuf_wrappers.js @@ -0,0 +1,128 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * Wrapper message for `double`. + * + * The JSON representation for `DoubleValue` is JSON number. + * + * @external "google.protobuf.DoubleValue" + * @property {number} value + * The double value. + * + * @see [google.protobuf.DoubleValue definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/wrappers.proto} + */ + +/** + * Wrapper message for `float`. + * + * The JSON representation for `FloatValue` is JSON number. + * + * @external "google.protobuf.FloatValue" + * @property {number} value + * The float value. + * + * @see [google.protobuf.FloatValue definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/wrappers.proto} + */ + +/** + * Wrapper message for `int64`. + * + * The JSON representation for `Int64Value` is JSON string. + * + * @external "google.protobuf.Int64Value" + * @property {number} value + * The int64 value. + * + * @see [google.protobuf.Int64Value definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/wrappers.proto} + */ + +/** + * Wrapper message for `uint64`. + * + * The JSON representation for `UInt64Value` is JSON string. + * + * @external "google.protobuf.UInt64Value" + * @property {number} value + * The uint64 value. + * + * @see [google.protobuf.UInt64Value definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/wrappers.proto} + */ + +/** + * Wrapper message for `int32`. + * + * The JSON representation for `Int32Value` is JSON number. + * + * @external "google.protobuf.Int32Value" + * @property {number} value + * The int32 value. + * + * @see [google.protobuf.Int32Value definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/wrappers.proto} + */ + +/** + * Wrapper message for `uint32`. + * + * The JSON representation for `UInt32Value` is JSON number. + * + * @external "google.protobuf.UInt32Value" + * @property {number} value + * The uint32 value. + * + * @see [google.protobuf.UInt32Value definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/wrappers.proto} + */ + +/** + * Wrapper message for `bool`. + * + * The JSON representation for `BoolValue` is JSON `true` and `false`. + * + * @external "google.protobuf.BoolValue" + * @property {boolean} value + * The bool value. + * + * @see [google.protobuf.BoolValue definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/wrappers.proto} + */ + +/** + * Wrapper message for `string`. + * + * The JSON representation for `StringValue` is JSON string. + * + * @external "google.protobuf.StringValue" + * @property {string} value + * The string value. + * + * @see [google.protobuf.StringValue definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/wrappers.proto} + */ + +/** + * Wrapper message for `bytes`. + * + * The JSON representation for `BytesValue` is JSON string. + * + * @external "google.protobuf.BytesValue" + * @property {string} value + * The bytes value. + * + * @see [google.protobuf.BytesValue definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/wrappers.proto} + */ \ No newline at end of file diff --git a/packages/datastore/src/doc_query.js b/packages/datastore/src/doc_query.js new file mode 100644 index 00000000000..90c44904ce8 --- /dev/null +++ b/packages/datastore/src/doc_query.js @@ -0,0 +1,489 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * The result of fetching an entity from Datastore. + * + * @property {Object} entity + * The resulting entity. + * + * This object should have the same structure as [Entity]{@link Entity} + * + * @property {number} version + * The version of the entity, a strictly positive number that monotonically + * increases with changes to the entity. + * + * This field is set for {@link `FULL`} entity + * results. + * + * For {@link missing} entities in `LookupResponse`, this + * is the version of the snapshot that was used to look up the entity, and it + * is always set except for eventually consistent reads. + * + * @property {string} cursor + * A cursor that points to the position after the result entity. + * Set only when the `EntityResult` is part of a `QueryResultBatch` message. + * + * @class + * @see [google.datastore.v1.EntityResult definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/query.proto} + */ +var EntityResult = { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * Specifies what data the 'entity' field contains. + * A `ResultType` is either implied (for example, in `LookupResponse.missing` + * from `datastore.proto`, it is always `KEY_ONLY`) or specified by context + * (for example, in message `QueryResultBatch`, field `entity_result_type` + * specifies a `ResultType` for all the values in field `entity_results`). + * + * @enum {number} + */ + ResultType: { + + /** + * Unspecified. This value is never used. + */ + RESULT_TYPE_UNSPECIFIED: 0, + + /** + * The key and properties. + */ + FULL: 1, + + /** + * A projected subset of properties. The entity may have no key. + */ + PROJECTION: 2, + + /** + * Only the key. + */ + KEY_ONLY: 3 + } +}; + +/** + * A query for entities. + * + * @property {Object[]} projection + * The projection to return. Defaults to returning all properties. + * + * This object should have the same structure as [Projection]{@link Projection} + * + * @property {Object[]} kind + * The kinds to query (if empty, returns entities of all kinds). + * Currently at most 1 kind may be specified. + * + * This object should have the same structure as [KindExpression]{@link KindExpression} + * + * @property {Object} filter + * The filter to apply. + * + * This object should have the same structure as [Filter]{@link Filter} + * + * @property {Object[]} order + * The order to apply to the query results (if empty, order is unspecified). + * + * This object should have the same structure as [PropertyOrder]{@link PropertyOrder} + * + * @property {Object[]} distinctOn + * The properties to make distinct. The query results will contain the first + * result for each distinct combination of values for the given properties + * (if empty, all results are returned). + * + * This object should have the same structure as [PropertyReference]{@link PropertyReference} + * + * @property {string} startCursor + * A starting point for the query results. Query cursors are + * returned in query result batches and + * [can only be used to continue the same query](https://cloud.google.com/datastore/docs/concepts/queries#cursors_limits_and_offsets). + * + * @property {string} endCursor + * An ending point for the query results. Query cursors are + * returned in query result batches and + * [can only be used to limit the same query](https://cloud.google.com/datastore/docs/concepts/queries#cursors_limits_and_offsets). + * + * @property {number} offset + * The number of results to skip. Applies before limit, but after all other + * constraints. Optional. Must be >= 0 if specified. + * + * @property {Object} limit + * The maximum number of results to return. Applies after all other + * constraints. Optional. + * Unspecified is interpreted as no limit. + * Must be >= 0 if specified. + * + * This object should have the same structure as [google.protobuf.Int32Value]{@link external:"google.protobuf.Int32Value"} + * + * @class + * @see [google.datastore.v1.Query definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/query.proto} + */ +var Query = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A representation of a kind. + * + * @property {string} name + * The name of the kind. + * + * @class + * @see [google.datastore.v1.KindExpression definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/query.proto} + */ +var KindExpression = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A reference to a property relative to the kind expressions. + * + * @property {string} name + * The name of the property. + * If name includes "."s, it may be interpreted as a property name path. + * + * @class + * @see [google.datastore.v1.PropertyReference definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/query.proto} + */ +var PropertyReference = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A representation of a property in a projection. + * + * @property {Object} property + * The property to project. + * + * This object should have the same structure as [PropertyReference]{@link PropertyReference} + * + * @class + * @see [google.datastore.v1.Projection definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/query.proto} + */ +var Projection = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The desired order for a specific property. + * + * @property {Object} property + * The property to order by. + * + * This object should have the same structure as [PropertyReference]{@link PropertyReference} + * + * @property {number} direction + * The direction to order by. Defaults to `ASCENDING`. + * + * The number should be among the values of [Direction]{@link Direction} + * + * @class + * @see [google.datastore.v1.PropertyOrder definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/query.proto} + */ +var PropertyOrder = { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * The sort direction. + * + * @enum {number} + */ + Direction: { + + /** + * Unspecified. This value must not be used. + */ + DIRECTION_UNSPECIFIED: 0, + + /** + * Ascending. + */ + ASCENDING: 1, + + /** + * Descending. + */ + DESCENDING: 2 + } +}; + +/** + * A holder for any type of filter. + * + * @property {Object} compositeFilter + * A composite filter. + * + * This object should have the same structure as [CompositeFilter]{@link CompositeFilter} + * + * @property {Object} propertyFilter + * A filter on a property. + * + * This object should have the same structure as [PropertyFilter]{@link PropertyFilter} + * + * @class + * @see [google.datastore.v1.Filter definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/query.proto} + */ +var Filter = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A filter that merges multiple other filters using the given operator. + * + * @property {number} op + * The operator for combining multiple filters. + * + * The number should be among the values of [Operator]{@link Operator} + * + * @property {Object[]} filters + * The list of filters to combine. + * Must contain at least one filter. + * + * This object should have the same structure as [Filter]{@link Filter} + * + * @class + * @see [google.datastore.v1.CompositeFilter definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/query.proto} + */ +var CompositeFilter = { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * A composite filter operator. + * + * @enum {number} + */ + Operator: { + + /** + * Unspecified. This value must not be used. + */ + OPERATOR_UNSPECIFIED: 0, + + /** + * The results are required to satisfy each of the combined filters. + */ + AND: 1 + } +}; + +/** + * A filter on a specific property. + * + * @property {Object} property + * The property to filter by. + * + * This object should have the same structure as [PropertyReference]{@link PropertyReference} + * + * @property {number} op + * The operator to filter by. + * + * The number should be among the values of [Operator]{@link Operator} + * + * @property {Object} value + * The value to compare the property to. + * + * This object should have the same structure as [Value]{@link Value} + * + * @class + * @see [google.datastore.v1.PropertyFilter definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/query.proto} + */ +var PropertyFilter = { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * A property filter operator. + * + * @enum {number} + */ + Operator: { + + /** + * Unspecified. This value must not be used. + */ + OPERATOR_UNSPECIFIED: 0, + + /** + * Less than. + */ + LESS_THAN: 1, + + /** + * Less than or equal. + */ + LESS_THAN_OR_EQUAL: 2, + + /** + * Greater than. + */ + GREATER_THAN: 3, + + /** + * Greater than or equal. + */ + GREATER_THAN_OR_EQUAL: 4, + + /** + * Equal. + */ + EQUAL: 5, + + /** + * Has ancestor. + */ + HAS_ANCESTOR: 11 + } +}; + +/** + * A [GQL query](https://cloud.google.com/datastore/docs/apis/gql/gql_reference). + * + * @property {string} queryString + * A string of the format described + * [here](https://cloud.google.com/datastore/docs/apis/gql/gql_reference). + * + * @property {boolean} allowLiterals + * When false, the query string must not contain any literals and instead must + * bind all values. For example, + * `SELECT * FROM Kind WHERE a = 'string literal'` is not allowed, while + * `SELECT * FROM Kind WHERE a = @value` is. + * + * @property {Object.} namedBindings + * For each non-reserved named binding site in the query string, there must be + * a named parameter with that name, but not necessarily the inverse. + * + * Key must match regex `[A-Za-z_$][A-Za-z_$0-9]*`, must not match regex + * `__.*__`, and must not be `""`. + * + * @property {Object[]} positionalBindings + * Numbered binding site @1 references the first numbered parameter, + * effectively using 1-based indexing, rather than the usual 0. + * + * For each binding site numbered i in `query_string`, there must be an i-th + * numbered parameter. The inverse must also be true. + * + * This object should have the same structure as [GqlQueryParameter]{@link GqlQueryParameter} + * + * @class + * @see [google.datastore.v1.GqlQuery definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/query.proto} + */ +var GqlQuery = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A binding parameter for a GQL query. + * + * @property {Object} value + * A value parameter. + * + * This object should have the same structure as [Value]{@link Value} + * + * @property {string} cursor + * A query cursor. Query cursors are returned in query + * result batches. + * + * @class + * @see [google.datastore.v1.GqlQueryParameter definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/query.proto} + */ +var GqlQueryParameter = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A batch of results produced by a query. + * + * @property {number} skippedResults + * The number of results skipped, typically because of an offset. + * + * @property {string} skippedCursor + * A cursor that points to the position after the last skipped result. + * Will be set when `skipped_results` != 0. + * + * @property {number} entityResultType + * The result type for every entity in `entity_results`. + * + * The number should be among the values of [ResultType]{@link ResultType} + * + * @property {Object[]} entityResults + * The results for this batch. + * + * This object should have the same structure as [EntityResult]{@link EntityResult} + * + * @property {string} endCursor + * A cursor that points to the position after the last result in the batch. + * + * @property {number} moreResults + * The state of the query after the current batch. + * + * The number should be among the values of [MoreResultsType]{@link MoreResultsType} + * + * @property {number} snapshotVersion + * The version number of the snapshot this batch was returned from. + * This applies to the range of results from the query's `start_cursor` (or + * the beginning of the query if no cursor was given) to this batch's + * `end_cursor` (not the query's `end_cursor`). + * + * In a single transaction, subsequent query result batches for the same query + * can have a greater snapshot version number. Each batch's snapshot version + * is valid for all preceding batches. + * The value will be zero for eventually consistent queries. + * + * @class + * @see [google.datastore.v1.QueryResultBatch definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/query.proto} + */ +var QueryResultBatch = { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * The possible values for the `more_results` field. + * + * @enum {number} + */ + MoreResultsType: { + + /** + * Unspecified. This value is never used. + */ + MORE_RESULTS_TYPE_UNSPECIFIED: 0, + + /** + * There may be additional batches to fetch from this query. + */ + NOT_FINISHED: 1, + + /** + * The query is finished, but there may be more results after the limit. + */ + MORE_RESULTS_AFTER_LIMIT: 2, + + /** + * The query is finished, but there may be more results after the end + * cursor. + */ + MORE_RESULTS_AFTER_CURSOR: 4, + + /** + * The query has been exhausted. + */ + NO_MORE_RESULTS: 3 + } +}; \ No newline at end of file From 8a55b9e52ec8208fc1a993f0ebe10b47d2961c17 Mon Sep 17 00:00:00 2001 From: Song Wang Date: Mon, 5 Jun 2017 18:54:37 -0700 Subject: [PATCH 02/17] Move dummy doc js files to separate doc directory --- packages/datastore/src/{ => v1/doc}/doc_datastore.js | 0 packages/datastore/src/{ => v1/doc}/doc_entity.js | 0 .../datastore/src/{ => v1/doc}/doc_google_protobuf_wrappers.js | 0 packages/datastore/src/{ => v1/doc}/doc_query.js | 0 4 files changed, 0 insertions(+), 0 deletions(-) rename packages/datastore/src/{ => v1/doc}/doc_datastore.js (100%) rename packages/datastore/src/{ => v1/doc}/doc_entity.js (100%) rename packages/datastore/src/{ => v1/doc}/doc_google_protobuf_wrappers.js (100%) rename packages/datastore/src/{ => v1/doc}/doc_query.js (100%) diff --git a/packages/datastore/src/doc_datastore.js b/packages/datastore/src/v1/doc/doc_datastore.js similarity index 100% rename from packages/datastore/src/doc_datastore.js rename to packages/datastore/src/v1/doc/doc_datastore.js diff --git a/packages/datastore/src/doc_entity.js b/packages/datastore/src/v1/doc/doc_entity.js similarity index 100% rename from packages/datastore/src/doc_entity.js rename to packages/datastore/src/v1/doc/doc_entity.js diff --git a/packages/datastore/src/doc_google_protobuf_wrappers.js b/packages/datastore/src/v1/doc/doc_google_protobuf_wrappers.js similarity index 100% rename from packages/datastore/src/doc_google_protobuf_wrappers.js rename to packages/datastore/src/v1/doc/doc_google_protobuf_wrappers.js diff --git a/packages/datastore/src/doc_query.js b/packages/datastore/src/v1/doc/doc_query.js similarity index 100% rename from packages/datastore/src/doc_query.js rename to packages/datastore/src/v1/doc/doc_query.js From 555eaa6fafe90cc64c5d61f4413fb6a097dffc7a Mon Sep 17 00:00:00 2001 From: Stephen Sawchuk Date: Mon, 5 Jun 2017 16:20:10 -0400 Subject: [PATCH 03/17] docs --- package.json | 2 + .../datastore/src/v1/doc/doc_datastore.js | 51 +++---- scripts/docs/builder.js | 56 ++++++- scripts/docs/parser.js | 140 +++++++++++++++++- 4 files changed, 211 insertions(+), 38 deletions(-) diff --git a/package.json b/package.json index 250af1d5b34..834f93a494a 100644 --- a/package.json +++ b/package.json @@ -15,8 +15,10 @@ "is": "^3.1.0", "jscs": "^2.1.1", "jshint": "^2.9.1", + "lodash.camelcase": "^4.3.0", "lodash.flatten": "^4.3.0", "lodash.template": "^4.3.0", + "lodash.upperfirst": "^4.3.1", "mitm": "^1.1.0", "mocha": "^2.5.3", "multiline": "^1.0.2", diff --git a/packages/datastore/src/v1/doc/doc_datastore.js b/packages/datastore/src/v1/doc/doc_datastore.js index 3ff2ec875f0..0471b2cccaf 100644 --- a/packages/datastore/src/v1/doc/doc_datastore.js +++ b/packages/datastore/src/v1/doc/doc_datastore.js @@ -22,21 +22,14 @@ /** * The request for {@link Datastore.Lookup}. * - * @property {string} projectId - * The ID of the project against which to make the request. - * - * @property {Object} readOptions - * The options for this lookup request. - * - * This object should have the same structure as [ReadOptions]{@link ReadOptions} - * - * @property {Object[]} keys - * Keys of entities to look up. - * - * This object should have the same structure as [Key]{@link Key} + * @property {string} projectId - The ID of the project against which to make the request. + * @property {Object} readOptions - The options for this lookup request. + * This object should have the same structure as [ReadOptions]{@link ReadOptions} + * @property {Object[]} keys Keys of entities to look up. + * This object should have the same structure as [Key]{@link Key} * * @class - * @see [google.datastore.v1.LookupRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + * @resource [google.datastore.v1.LookupRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} */ var LookupRequest = { // This is for documentation. Actual contents will be loaded by gRPC. @@ -45,14 +38,14 @@ var LookupRequest = { /** * The response for {@link Datastore.Lookup}. * - * @property {Object[]} found + * @param {Object[]} found * Entities found as `ResultType.FULL` entities. The order of results in this * field is undefined and has no relation to the order of the keys in the * input. * * This object should have the same structure as [EntityResult]{@link EntityResult} * - * @property {Object[]} missing + * @param {Object[]} missing * Entities not found as `ResultType.KEY_ONLY` entities. The order of results * in this field is undefined and has no relation to the order of the keys * in the input. @@ -67,7 +60,7 @@ var LookupRequest = { * This object should have the same structure as [Key]{@link Key} * * @class - * @see [google.datastore.v1.LookupResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + * @resource [google.datastore.v1.LookupResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} */ var LookupResponse = { // This is for documentation. Actual contents will be loaded by gRPC. @@ -103,7 +96,7 @@ var LookupResponse = { * This object should have the same structure as [GqlQuery]{@link GqlQuery} * * @class - * @see [google.datastore.v1.RunQueryRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + * @resource [google.datastore.v1.RunQueryRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} */ var RunQueryRequest = { // This is for documentation. Actual contents will be loaded by gRPC. @@ -123,7 +116,7 @@ var RunQueryRequest = { * This object should have the same structure as [Query]{@link Query} * * @class - * @see [google.datastore.v1.RunQueryResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + * @resource [google.datastore.v1.RunQueryResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} */ var RunQueryResponse = { // This is for documentation. Actual contents will be loaded by gRPC. @@ -136,7 +129,7 @@ var RunQueryResponse = { * The ID of the project against which to make the request. * * @class - * @see [google.datastore.v1.BeginTransactionRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + * @resource [google.datastore.v1.BeginTransactionRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} */ var BeginTransactionRequest = { // This is for documentation. Actual contents will be loaded by gRPC. @@ -149,7 +142,7 @@ var BeginTransactionRequest = { * The transaction identifier (always present). * * @class - * @see [google.datastore.v1.BeginTransactionResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + * @resource [google.datastore.v1.BeginTransactionResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} */ var BeginTransactionResponse = { // This is for documentation. Actual contents will be loaded by gRPC. @@ -166,7 +159,7 @@ var BeginTransactionResponse = { * {@link Datastore.BeginTransaction}. * * @class - * @see [google.datastore.v1.RollbackRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + * @resource [google.datastore.v1.RollbackRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} */ var RollbackRequest = { // This is for documentation. Actual contents will be loaded by gRPC. @@ -176,7 +169,7 @@ var RollbackRequest = { * The response for {@link Datastore.Rollback}. * (an empty message). * @class - * @see [google.datastore.v1.RollbackResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + * @resource [google.datastore.v1.RollbackResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} */ var RollbackResponse = { // This is for documentation. Actual contents will be loaded by gRPC. @@ -216,7 +209,7 @@ var RollbackResponse = { * This object should have the same structure as [Mutation]{@link Mutation} * * @class - * @see [google.datastore.v1.CommitRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + * @resource [google.datastore.v1.CommitRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} */ var CommitRequest = { // This is for documentation. Actual contents will be loaded by gRPC. @@ -260,7 +253,7 @@ var CommitRequest = { * updated. * * @class - * @see [google.datastore.v1.CommitResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + * @resource [google.datastore.v1.CommitResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} */ var CommitResponse = { // This is for documentation. Actual contents will be loaded by gRPC. @@ -279,7 +272,7 @@ var CommitResponse = { * This object should have the same structure as [Key]{@link Key} * * @class - * @see [google.datastore.v1.AllocateIdsRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + * @resource [google.datastore.v1.AllocateIdsRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} */ var AllocateIdsRequest = { // This is for documentation. Actual contents will be loaded by gRPC. @@ -295,7 +288,7 @@ var AllocateIdsRequest = { * This object should have the same structure as [Key]{@link Key} * * @class - * @see [google.datastore.v1.AllocateIdsResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + * @resource [google.datastore.v1.AllocateIdsResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} */ var AllocateIdsResponse = { // This is for documentation. Actual contents will be loaded by gRPC. @@ -333,7 +326,7 @@ var AllocateIdsResponse = { * does not match the current version on the server, the mutation conflicts. * * @class - * @see [google.datastore.v1.Mutation definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + * @resource [google.datastore.v1.Mutation definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} */ var Mutation = { // This is for documentation. Actual contents will be loaded by gRPC. @@ -360,7 +353,7 @@ var Mutation = { * conflict detection strategy field is not set in the mutation. * * @class - * @see [google.datastore.v1.MutationResult definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + * @resource [google.datastore.v1.MutationResult definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} */ var MutationResult = { // This is for documentation. Actual contents will be loaded by gRPC. @@ -381,7 +374,7 @@ var MutationResult = { * {@link Datastore.BeginTransaction}. * * @class - * @see [google.datastore.v1.ReadOptions definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + * @resource [google.datastore.v1.ReadOptions definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} */ var ReadOptions = { // This is for documentation. Actual contents will be loaded by gRPC. diff --git a/scripts/docs/builder.js b/scripts/docs/builder.js index 08689bd6306..384f9daa95c 100644 --- a/scripts/docs/builder.js +++ b/scripts/docs/builder.js @@ -76,7 +76,13 @@ Builder.prototype.build = function() { mkdir('-p', this.dir); cp(MARKDOWN, this.dir); - var docs = globby.sync(path.join(this.name, 'src/*.js'), { + var docsPaths = [ + path.join(this.name, 'src/*.js'), + path.join(this.name, 'src/**/v*/doc/*.js'), + path.join(this.name, 'src/**/v*/*_client.js') + ]; + + var docs = globby.sync(docsPaths, { cwd: PACKAGES_ROOT, ignore: config.IGNORE }).map(function(file) { @@ -89,6 +95,54 @@ Builder.prototype.build = function() { return json; }); + var gapicVersions = docs.reduce((grouped, doc) => { + var gapicVersion = doc.id.match(/\/(v[^\/]*)/); + + if (gapicVersion) { + gapicVersion = gapicVersion[1]; + mkdir('-p', `${self.dir}/${gapicVersion}`); + + if (doc.id.includes('doc_')) { + grouped[gapicVersion] = grouped[gapicVersion] || []; + grouped[gapicVersion].push(doc); + } else if (doc.id.includes('_client')) { + // Move client file to a separate path. + doc.path = `${gapicVersion}/${doc.path}`; + self.write(doc.path, doc); + } + } + + return grouped; + }, {}); + + // @TODO delete extra files + docs = docs.filter(doc => !doc.source.includes('doc_')); + + for (var gapicVersion in gapicVersions) { + var gapicFiles = gapicVersions[gapicVersion]; + + var dataTypesFile = gapicFiles.reduce((dataTypesFile, gapicFile) => { + if (!dataTypesFile.id) { + var idParts = gapicFile.id.split('/'); + idParts.pop(); + idParts.pop(); + idParts.push('data_types'); + dataTypesFile.id = idParts.join('/'); + } + + dataTypesFile.methods = dataTypesFile.methods.concat(gapicFile.methods); + + return dataTypesFile; + }, { + methods: [], + path: `${gapicVersion}/data_types.json` + }); + + this.write(`${gapicVersion}/data_types.json`, dataTypesFile); + + docs.push(dataTypesFile); + } + var types = parser.createTypesDictionary(docs); var toc = parser.createToc(types); diff --git a/scripts/docs/parser.js b/scripts/docs/parser.js index 20c4a8fde3a..2ccc6d753df 100644 --- a/scripts/docs/parser.js +++ b/scripts/docs/parser.js @@ -16,14 +16,17 @@ 'use strict'; +var camel = require('lodash.camelcase'); var dox = require('dox'); -var globby = require('globby'); var fs = require('fs'); -var path = require('path'); +var extend = require('extend'); var format = require('string-format-obj'); +var globby = require('globby'); +var path = require('path'); var prop = require('propprop'); -var extend = require('extend'); var template = require('lodash.template'); +var upperFirst = require('lodash.upperfirst'); + var config = require('./config'); var baseToc = require('./templates/toc.json'); @@ -52,7 +55,7 @@ function detectLinks(str) { function formatHtml(html) { var formatted = (html || '') .replace(/\s+/g, ' ') - .replace(/
/g, ' ') + .replace(/
/g, ' ') /* TODO: remove. fixing a sublime text bug */ .replace(/`([^`]*)`/g, '$1'); return detectLinks(detectCustomType(formatted)); @@ -63,6 +66,7 @@ function detectCustomType(str) { var templateFn = format.bind(null, tmpl); var rCustomType = /\{*module\:([^\}|\>]*)\}*/g; var rArray = /Array\.<(.+)>/g; + var rProtoType = /{@link ([A-Z][^}]*)}/; return str .replace(rArray, function(match, module) { @@ -76,6 +80,15 @@ function detectCustomType(str) { method: parts[1] || '', text: module }); + }) + .replace(rProtoType, function(match, protoType) { + return protoType; + // // @TODO link-ability + // return templateFn({ + // module: 'data_types', + // method: protoType, + // text: protoType + // }); }); } @@ -251,6 +264,20 @@ function createReturn(tag) { function createMethod(fileName, parent, block) { var name = getName(block); + var allParams = getTagsByType(block, 'param') + .concat(getTagsByType(block, 'property')) + .map(createParam); + + var isGapic = fileName.includes('doc_'); + var isRequestOrResponse = + name && (name.includes('Request') || name.includes('Response')); + + if (isGapic && isRequestOrResponse) { + // Ignore descriptions that have links we don't want, e.g. + // "The request for {@link Datastore.AllocateIds}." + block.description = {}; + } + return { id: name, name: name, @@ -259,7 +286,7 @@ function createMethod(fileName, parent, block) { source: path.normalize(fileName) + '#L' + block.codeStart, resources: getTagsByType(block, 'resource').map(createResource), examples: createExamples(block), - params: getTagsByType(block, 'param').map(createParam), + params: allParams, exceptions: getTagsByType(block, 'throws').map(createException), returns: getTagsByType(block, 'return').map(createReturn) }; @@ -316,29 +343,67 @@ function parseFile(fileName, contents, umbrellaMode) { function createTypesDictionary(docs) { return docs.map(function(service) { + var isGapic = /_client$/.test(service.id); + + var titleParts = []; var id = service.id; - var title = [id === config.UMBRELLA_PACKAGE ? 'Google Cloud' : service.name]; var contents = service.path; + if (id === config.UMBRELLA_PACKAGE) { + titleParts.push('Google Cloud'); + } else { + titleParts.push(service.name); + } + + if (isGapic) { + var gapicVersion; + var gapicPath = service.id.split('/'); + var versionIndex; + + gapicPath.forEach(function(gapicPathPart, index) { + if (/v\d/.test(gapicPathPart)) { + gapicVersion = gapicPathPart; + versionIndex = index; + } + }); + + titleParts = [gapicVersion]; + + var nestedTitle = [].slice.call(gapicPath).slice(1, versionIndex); + + if (nestedTitle.length > 0) { + nestedTitle = nestedTitle.map(upperFirst).join('/'); + titleParts.push(nestedTitle); + } + } + if (service.parent) { for (var i = 0, l = docs.length; i < l; i++) { if (docs[i].id === service.parent) { - title.unshift(docs[i].name); + titleParts.unshift(docs[i].name); } } } return { id: id, - title: title, + title: titleParts, contents: contents }; }); } function createToc(types, collapse) { + var PATH_VERSION_REGEX = /\/(v[^/]*)/; + var toc = extend(true, {}, baseToc); + + var generatedTypes = types.filter(type => / v\d/.test(type.title.join(' '))); + var protos = types.filter(type => type.id.includes('/doc/')); + var protosGroupedByVersion = {}; + var services = types + .filter(type => !generatedTypes.includes(type) && !protos.includes(type)) .map(function(type) { return { type: type.id, @@ -357,6 +422,65 @@ function createToc(types, collapse) { return a.type < b.type ? -1 : a.type > b.type ? 1 : 0; }); + if (protos.length > 0) { + protos.forEach(function(proto) { + var version = proto.id.match(PATH_VERSION_REGEX)[1]; + protosGroupedByVersion[version] = protosGroupedByVersion[version] || []; + protosGroupedByVersion[version].push(proto); + }); + } + + if (generatedTypes.length > 0) { + // Push the generated types to the bottom of the navigation. + var generatedTypesByVersion = {}; + + generatedTypes.forEach(function(generatedType) { + var version = generatedType.title[1]; + generatedTypesByVersion[version] = generatedTypesByVersion[version] || []; + generatedTypesByVersion[version].push(generatedType); + }); + + for (var version in generatedTypesByVersion) { + var generatedTypesGrouped = generatedTypesByVersion[version] + .sort(function(a, b) { + if (a.title.length < b.title.length) { // e.g. ['Spanner', 'v1'] + return -1; + } + + if (b.title.length < a.title.length) { + return 1; + } + + var titleA = a.title[a.title.length - 1]; + var titleB = b.title[b.title.length - 1]; + + return titleA < titleB ? -1 : titleA > titleB ? 1 : 0; + }); + + var parent = generatedTypesGrouped.shift(); + + var serviceObject = { + title: version, + type: parent.id, + nav: generatedTypesGrouped.map(function(generatedType) { + return { + title: generatedType.title[generatedType.title.length - 1], + type: generatedType.id + }; + }) + }; + + serviceObject.nav.push({ + title: 'Data Types', + type: parent.id.replace(/\/\w+_client$/, '/data_types') + }); + + services.push(serviceObject); + } + } + + services = services.filter(service => !service.type.includes('data_types')); + if (!collapse) { toc.services = services; return toc; From bc60b46f573b08dad0b097cde7f61f55245db0ce Mon Sep 17 00:00:00 2001 From: Stephen Sawchuk Date: Wed, 28 Jun 2017 16:10:48 -0400 Subject: [PATCH 04/17] restore --- .../datastore/src/v1/doc/doc_datastore.js | 51 +++++++++++-------- 1 file changed, 29 insertions(+), 22 deletions(-) diff --git a/packages/datastore/src/v1/doc/doc_datastore.js b/packages/datastore/src/v1/doc/doc_datastore.js index 0471b2cccaf..3ff2ec875f0 100644 --- a/packages/datastore/src/v1/doc/doc_datastore.js +++ b/packages/datastore/src/v1/doc/doc_datastore.js @@ -22,14 +22,21 @@ /** * The request for {@link Datastore.Lookup}. * - * @property {string} projectId - The ID of the project against which to make the request. - * @property {Object} readOptions - The options for this lookup request. - * This object should have the same structure as [ReadOptions]{@link ReadOptions} - * @property {Object[]} keys Keys of entities to look up. - * This object should have the same structure as [Key]{@link Key} + * @property {string} projectId + * The ID of the project against which to make the request. + * + * @property {Object} readOptions + * The options for this lookup request. + * + * This object should have the same structure as [ReadOptions]{@link ReadOptions} + * + * @property {Object[]} keys + * Keys of entities to look up. + * + * This object should have the same structure as [Key]{@link Key} * * @class - * @resource [google.datastore.v1.LookupRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + * @see [google.datastore.v1.LookupRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} */ var LookupRequest = { // This is for documentation. Actual contents will be loaded by gRPC. @@ -38,14 +45,14 @@ var LookupRequest = { /** * The response for {@link Datastore.Lookup}. * - * @param {Object[]} found + * @property {Object[]} found * Entities found as `ResultType.FULL` entities. The order of results in this * field is undefined and has no relation to the order of the keys in the * input. * * This object should have the same structure as [EntityResult]{@link EntityResult} * - * @param {Object[]} missing + * @property {Object[]} missing * Entities not found as `ResultType.KEY_ONLY` entities. The order of results * in this field is undefined and has no relation to the order of the keys * in the input. @@ -60,7 +67,7 @@ var LookupRequest = { * This object should have the same structure as [Key]{@link Key} * * @class - * @resource [google.datastore.v1.LookupResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + * @see [google.datastore.v1.LookupResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} */ var LookupResponse = { // This is for documentation. Actual contents will be loaded by gRPC. @@ -96,7 +103,7 @@ var LookupResponse = { * This object should have the same structure as [GqlQuery]{@link GqlQuery} * * @class - * @resource [google.datastore.v1.RunQueryRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + * @see [google.datastore.v1.RunQueryRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} */ var RunQueryRequest = { // This is for documentation. Actual contents will be loaded by gRPC. @@ -116,7 +123,7 @@ var RunQueryRequest = { * This object should have the same structure as [Query]{@link Query} * * @class - * @resource [google.datastore.v1.RunQueryResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + * @see [google.datastore.v1.RunQueryResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} */ var RunQueryResponse = { // This is for documentation. Actual contents will be loaded by gRPC. @@ -129,7 +136,7 @@ var RunQueryResponse = { * The ID of the project against which to make the request. * * @class - * @resource [google.datastore.v1.BeginTransactionRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + * @see [google.datastore.v1.BeginTransactionRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} */ var BeginTransactionRequest = { // This is for documentation. Actual contents will be loaded by gRPC. @@ -142,7 +149,7 @@ var BeginTransactionRequest = { * The transaction identifier (always present). * * @class - * @resource [google.datastore.v1.BeginTransactionResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + * @see [google.datastore.v1.BeginTransactionResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} */ var BeginTransactionResponse = { // This is for documentation. Actual contents will be loaded by gRPC. @@ -159,7 +166,7 @@ var BeginTransactionResponse = { * {@link Datastore.BeginTransaction}. * * @class - * @resource [google.datastore.v1.RollbackRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + * @see [google.datastore.v1.RollbackRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} */ var RollbackRequest = { // This is for documentation. Actual contents will be loaded by gRPC. @@ -169,7 +176,7 @@ var RollbackRequest = { * The response for {@link Datastore.Rollback}. * (an empty message). * @class - * @resource [google.datastore.v1.RollbackResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + * @see [google.datastore.v1.RollbackResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} */ var RollbackResponse = { // This is for documentation. Actual contents will be loaded by gRPC. @@ -209,7 +216,7 @@ var RollbackResponse = { * This object should have the same structure as [Mutation]{@link Mutation} * * @class - * @resource [google.datastore.v1.CommitRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + * @see [google.datastore.v1.CommitRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} */ var CommitRequest = { // This is for documentation. Actual contents will be loaded by gRPC. @@ -253,7 +260,7 @@ var CommitRequest = { * updated. * * @class - * @resource [google.datastore.v1.CommitResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + * @see [google.datastore.v1.CommitResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} */ var CommitResponse = { // This is for documentation. Actual contents will be loaded by gRPC. @@ -272,7 +279,7 @@ var CommitResponse = { * This object should have the same structure as [Key]{@link Key} * * @class - * @resource [google.datastore.v1.AllocateIdsRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + * @see [google.datastore.v1.AllocateIdsRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} */ var AllocateIdsRequest = { // This is for documentation. Actual contents will be loaded by gRPC. @@ -288,7 +295,7 @@ var AllocateIdsRequest = { * This object should have the same structure as [Key]{@link Key} * * @class - * @resource [google.datastore.v1.AllocateIdsResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + * @see [google.datastore.v1.AllocateIdsResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} */ var AllocateIdsResponse = { // This is for documentation. Actual contents will be loaded by gRPC. @@ -326,7 +333,7 @@ var AllocateIdsResponse = { * does not match the current version on the server, the mutation conflicts. * * @class - * @resource [google.datastore.v1.Mutation definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + * @see [google.datastore.v1.Mutation definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} */ var Mutation = { // This is for documentation. Actual contents will be loaded by gRPC. @@ -353,7 +360,7 @@ var Mutation = { * conflict detection strategy field is not set in the mutation. * * @class - * @resource [google.datastore.v1.MutationResult definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + * @see [google.datastore.v1.MutationResult definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} */ var MutationResult = { // This is for documentation. Actual contents will be loaded by gRPC. @@ -374,7 +381,7 @@ var MutationResult = { * {@link Datastore.BeginTransaction}. * * @class - * @resource [google.datastore.v1.ReadOptions definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + * @see [google.datastore.v1.ReadOptions definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} */ var ReadOptions = { // This is for documentation. Actual contents will be loaded by gRPC. From bf4f944bf15deda0c210a6311497661c138c2c1d Mon Sep 17 00:00:00 2001 From: Stephen Sawchuk Date: Wed, 28 Jun 2017 16:15:28 -0400 Subject: [PATCH 05/17] Update manifest for master [ci skip] --- .gitmodules | 4 ++++ gh-pages | 1 + 2 files changed, 5 insertions(+) create mode 100644 .gitmodules create mode 160000 gh-pages diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 00000000000..74b7512e04f --- /dev/null +++ b/.gitmodules @@ -0,0 +1,4 @@ +[submodule "gh-pages"] + path = gh-pages + url = https://github.com/GoogleCloudPlatform/google-cloud-node.git + branch = gh-pages diff --git a/gh-pages b/gh-pages new file mode 160000 index 00000000000..fbcb81d9ad8 --- /dev/null +++ b/gh-pages @@ -0,0 +1 @@ +Subproject commit fbcb81d9ad824fdc3a99cfc7b8bae4ae42b0ff40 From b6b1155648a303efccade54d155ee9cd4efa4d32 Mon Sep 17 00:00:00 2001 From: Stephen Sawchuk Date: Wed, 28 Jun 2017 16:43:58 -0400 Subject: [PATCH 06/17] remove links & add title to Data Types page --- scripts/docs/builder.js | 2 ++ scripts/docs/parser.js | 4 ++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/scripts/docs/builder.js b/scripts/docs/builder.js index 384f9daa95c..179dee2cd66 100644 --- a/scripts/docs/builder.js +++ b/scripts/docs/builder.js @@ -127,7 +127,9 @@ Builder.prototype.build = function() { idParts.pop(); idParts.pop(); idParts.push('data_types'); + dataTypesFile.id = idParts.join('/'); + dataTypesFile.name = 'Data Types'; } dataTypesFile.methods = dataTypesFile.methods.concat(gapicFile.methods); diff --git a/scripts/docs/parser.js b/scripts/docs/parser.js index 2ccc6d753df..0a8d8716fbe 100644 --- a/scripts/docs/parser.js +++ b/scripts/docs/parser.js @@ -66,7 +66,7 @@ function detectCustomType(str) { var templateFn = format.bind(null, tmpl); var rCustomType = /\{*module\:([^\}|\>]*)\}*/g; var rArray = /Array\.<(.+)>/g; - var rProtoType = /{@link ([A-Z][^}]*)}/; + var rProtoType = /\[\w+\]{@link ([A-Z][^}]*)}/g; return str .replace(rArray, function(match, module) { @@ -81,9 +81,9 @@ function detectCustomType(str) { text: module }); }) + // @TODO link-ability .replace(rProtoType, function(match, protoType) { return protoType; - // // @TODO link-ability // return templateFn({ // module: 'data_types', // method: protoType, From c89e6efc036ad9dc69cbcc9542006a06f1c65871 Mon Sep 17 00:00:00 2001 From: Stephen Sawchuk Date: Thu, 29 Jun 2017 14:05:51 -0400 Subject: [PATCH 07/17] support linking --- scripts/docs/builder.js | 39 +++++++++++++++++++++++++++++++++++++-- scripts/docs/parser.js | 11 ++++++----- 2 files changed, 43 insertions(+), 7 deletions(-) diff --git a/scripts/docs/builder.js b/scripts/docs/builder.js index 179dee2cd66..928c6c834b6 100644 --- a/scripts/docs/builder.js +++ b/scripts/docs/builder.js @@ -127,19 +127,54 @@ Builder.prototype.build = function() { idParts.pop(); idParts.pop(); idParts.push('data_types'); - dataTypesFile.id = idParts.join('/'); - dataTypesFile.name = 'Data Types'; } dataTypesFile.methods = dataTypesFile.methods.concat(gapicFile.methods); return dataTypesFile; }, { + name: 'Data Types', methods: [], path: `${gapicVersion}/data_types.json` }); + var description = ` + + + + + + + + + + + + + +
ClassDescription
+ + {{method.name}} + + + + {{method.description}} + + + The request for {{method.name}}. + + + The response for {{method.name}}. + +
+ `; + dataTypesFile.description = description; + + // dataTypesFile.description = dataTypesFile.methods.reduce((desc, method) => { + // desc += + // }, description); + this.write(`${gapicVersion}/data_types.json`, dataTypesFile); docs.push(dataTypesFile); diff --git a/scripts/docs/parser.js b/scripts/docs/parser.js index 0a8d8716fbe..310d5f3c102 100644 --- a/scripts/docs/parser.js +++ b/scripts/docs/parser.js @@ -83,12 +83,13 @@ function detectCustomType(str) { }) // @TODO link-ability .replace(rProtoType, function(match, protoType) { + return ` + ${protoType} + `.trim(); return protoType; - // return templateFn({ - // module: 'data_types', - // method: protoType, - // text: protoType - // }); }); } From 72945641993e5b0d4f90ff70a7c24d7535cc1b0a Mon Sep 17 00:00:00 2001 From: Stephen Sawchuk Date: Thu, 29 Jun 2017 14:08:27 -0400 Subject: [PATCH 08/17] tidy code --- scripts/docs/builder.js | 81 +++++++++++++++++++---------------------- scripts/docs/parser.js | 1 - 2 files changed, 38 insertions(+), 44 deletions(-) diff --git a/scripts/docs/builder.js b/scripts/docs/builder.js index 928c6c834b6..f669d60836a 100644 --- a/scripts/docs/builder.js +++ b/scripts/docs/builder.js @@ -121,7 +121,44 @@ Builder.prototype.build = function() { for (var gapicVersion in gapicVersions) { var gapicFiles = gapicVersions[gapicVersion]; - var dataTypesFile = gapicFiles.reduce((dataTypesFile, gapicFile) => { + var dataTypesFile = { + name: 'Data Types', + methods: [], + path: `${gapicVersion}/data_types.json`, + description: ` + + + + + + + + + + + + + +
ClassDescription
+ + {{method.name}} + + + + {{method.description}} + + + The request for {{method.name}}. + + + The response for {{method.name}}. + +
+ ` + }; + + /*jshint loopfunc:true*/ + gapicFiles.forEach(gapicFile => { if (!dataTypesFile.id) { var idParts = gapicFile.id.split('/'); idParts.pop(); @@ -131,50 +168,8 @@ Builder.prototype.build = function() { } dataTypesFile.methods = dataTypesFile.methods.concat(gapicFile.methods); - - return dataTypesFile; - }, { - name: 'Data Types', - methods: [], - path: `${gapicVersion}/data_types.json` }); - var description = ` - - - - - - - - - - - - - -
ClassDescription
- - {{method.name}} - - - - {{method.description}} - - - The request for {{method.name}}. - - - The response for {{method.name}}. - -
- `; - dataTypesFile.description = description; - - // dataTypesFile.description = dataTypesFile.methods.reduce((desc, method) => { - // desc += - // }, description); - this.write(`${gapicVersion}/data_types.json`, dataTypesFile); docs.push(dataTypesFile); diff --git a/scripts/docs/parser.js b/scripts/docs/parser.js index 310d5f3c102..dce1e9d0487 100644 --- a/scripts/docs/parser.js +++ b/scripts/docs/parser.js @@ -89,7 +89,6 @@ function detectCustomType(str) { method: '${protoType}' })">${protoType} `.trim(); - return protoType; }); } From fb630e80cd883b37524fc4b9a53881635cfdd5e2 Mon Sep 17 00:00:00 2001 From: Stephen Sawchuk Date: Thu, 29 Jun 2017 14:10:24 -0400 Subject: [PATCH 09/17] remove unused dep --- package.json | 1 - scripts/docs/parser.js | 1 - 2 files changed, 2 deletions(-) diff --git a/package.json b/package.json index 834f93a494a..01e6fc80727 100644 --- a/package.json +++ b/package.json @@ -15,7 +15,6 @@ "is": "^3.1.0", "jscs": "^2.1.1", "jshint": "^2.9.1", - "lodash.camelcase": "^4.3.0", "lodash.flatten": "^4.3.0", "lodash.template": "^4.3.0", "lodash.upperfirst": "^4.3.1", diff --git a/scripts/docs/parser.js b/scripts/docs/parser.js index dce1e9d0487..5c8db542c44 100644 --- a/scripts/docs/parser.js +++ b/scripts/docs/parser.js @@ -16,7 +16,6 @@ 'use strict'; -var camel = require('lodash.camelcase'); var dox = require('dox'); var fs = require('fs'); var extend = require('extend'); From 89ad5bce6db9da34bc2089ccbc1c056963b7df2a Mon Sep 17 00:00:00 2001 From: Stephen Sawchuk Date: Thu, 29 Jun 2017 14:42:48 -0400 Subject: [PATCH 10/17] correct link inside links --- scripts/docs/parser.js | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/scripts/docs/parser.js b/scripts/docs/parser.js index 5c8db542c44..6e696178fa6 100644 --- a/scripts/docs/parser.js +++ b/scripts/docs/parser.js @@ -44,11 +44,26 @@ function isMethod(block) { } function detectLinks(str) { + var linkInsideLink = /@link /g; var reg = /\[([^\]]*)]{@link ([^}]*)}/g; - return str.replace(reg, function(match, title, link) { - return '' + title.trim() + ''; - }); + return str + .replace(linkInsideLink, function(match, link) { + return `@link ${link}`; + }) + .replace(reg, function(match, title, link) { + // str = ` + // [gax.CallOptions]{@link https://googleapis.github.io/gax-nodejs/global.html#CallOptions} + // ` + + if (link.startsWith('external')) { + return title; + } + + link = link.replace('' + title.trim() + ''; + }); } function formatHtml(html) { From b68ee1379f2a19ecb8018caf00cf877cdcecccfc Mon Sep 17 00:00:00 2001 From: Stephen Sawchuk Date: Thu, 29 Jun 2017 14:43:27 -0400 Subject: [PATCH 11/17] remove debugging --- scripts/docs/parser.js | 4 ---- 1 file changed, 4 deletions(-) diff --git a/scripts/docs/parser.js b/scripts/docs/parser.js index 6e696178fa6..3f0cd48d5aa 100644 --- a/scripts/docs/parser.js +++ b/scripts/docs/parser.js @@ -52,10 +52,6 @@ function detectLinks(str) { return `@link ${link}`; }) .replace(reg, function(match, title, link) { - // str = ` - // [gax.CallOptions]{@link https://googleapis.github.io/gax-nodejs/global.html#CallOptions} - // ` - if (link.startsWith('external')) { return title; } From 338f4e5499e3506bedaafcf1cf1b1cbcfa950ef5 Mon Sep 17 00:00:00 2001 From: Stephen Sawchuk Date: Thu, 29 Jun 2017 14:48:31 -0400 Subject: [PATCH 12/17] mark client as constructor so method listing shows --- scripts/docs/parser.js | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/scripts/docs/parser.js b/scripts/docs/parser.js index 3f0cd48d5aa..d52d7e94563 100644 --- a/scripts/docs/parser.js +++ b/scripts/docs/parser.js @@ -181,6 +181,10 @@ function getMethodType(block) { return 'constructor'; } + if (block.ctx && block.ctx.name.endsWith('Client')) { + return 'constructor'; + } + if (getTagsByType(block, 'static').length > 0) { return 'static'; } From 60abf5ddc021673777f03e4fb27957a80b00893f Mon Sep 17 00:00:00 2001 From: Stephen Sawchuk Date: Thu, 29 Jun 2017 14:53:51 -0400 Subject: [PATCH 13/17] correctly identify clients --- scripts/docs/parser.js | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/scripts/docs/parser.js b/scripts/docs/parser.js index d52d7e94563..3d25b32253d 100644 --- a/scripts/docs/parser.js +++ b/scripts/docs/parser.js @@ -181,8 +181,12 @@ function getMethodType(block) { return 'constructor'; } - if (block.ctx && block.ctx.name.endsWith('Client')) { - return 'constructor'; + if (block.ctx) { + var name = block.ctx.name; + + if (/^[A-Z]/.test(name) && name.endsWith('Client')) { + return 'constructor'; + } } if (getTagsByType(block, 'static').length > 0) { From e5ec5b2024ce23739bd3b22634a1011d580388e6 Mon Sep 17 00:00:00 2001 From: Stephen Sawchuk Date: Thu, 29 Jun 2017 18:39:58 -0400 Subject: [PATCH 14/17] create overview, move client to their own nav items --- package.json | 3 +++ scripts/docs/builder.js | 51 ++++++++++++++++++++++++++++++++++++++--- scripts/docs/parser.js | 39 +++++++++++++++++++++++-------- 3 files changed, 80 insertions(+), 13 deletions(-) diff --git a/package.json b/package.json index 01e6fc80727..e0d6b86163f 100644 --- a/package.json +++ b/package.json @@ -72,5 +72,8 @@ "license": "Apache-2.0", "engines": { "node": ">=4.0.0" + }, + "dependencies": { + "lodash.camelcase": "^4.3.0" } } diff --git a/scripts/docs/builder.js b/scripts/docs/builder.js index f669d60836a..4bbc3a408c7 100644 --- a/scripts/docs/builder.js +++ b/scripts/docs/builder.js @@ -22,6 +22,7 @@ var chalk = require('chalk'); var flatten = require('lodash.flatten'); var fs = require('fs'); var globby = require('globby'); +var is = require('is'); var path = require('path'); var semver = require('semver'); @@ -95,6 +96,7 @@ Builder.prototype.build = function() { return json; }); + var gapicVersions = docs.reduce((grouped, doc) => { var gapicVersion = doc.id.match(/\/(v[^\/]*)/); @@ -121,6 +123,48 @@ Builder.prototype.build = function() { for (var gapicVersion in gapicVersions) { var gapicFiles = gapicVersions[gapicVersion]; + this.write(`${gapicVersion}/index.json`, { + name: gapicVersion, + methods: [], + path: `${gapicVersion}/index.json`, + description: ` +

{{docs.services[0].title}} API Contents

+ + + + + + + + + + + + + + + + + + +
ClassDescription
+ {{client.title}} + + Create a {{client.title}} to interact with the {{docs.services[0].title}} API. +
+ Data Types + + Data types for {{docs.services[0].title}} {{service.path.split('/').shift()}}. +
+ ` + }); + var dataTypesFile = { name: 'Data Types', methods: [], @@ -170,9 +214,10 @@ Builder.prototype.build = function() { dataTypesFile.methods = dataTypesFile.methods.concat(gapicFile.methods); }); - this.write(`${gapicVersion}/data_types.json`, dataTypesFile); - - docs.push(dataTypesFile); + if (!is.empty(dataTypesFile.methods)) { + this.write(`${gapicVersion}/data_types.json`, dataTypesFile); + docs.push(dataTypesFile); + } } var types = parser.createTypesDictionary(docs); diff --git a/scripts/docs/parser.js b/scripts/docs/parser.js index 3d25b32253d..6865ee468b0 100644 --- a/scripts/docs/parser.js +++ b/scripts/docs/parser.js @@ -16,6 +16,7 @@ 'use strict'; +var camel = require('lodash.camelcase'); var dox = require('dox'); var fs = require('fs'); var extend = require('extend'); @@ -360,7 +361,10 @@ function parseFile(fileName, contents, umbrellaMode) { } function createTypesDictionary(docs) { - return docs.map(function(service) { + var types = []; + var gapicVersions = []; + + docs.forEach(function(service) { var isGapic = /_client$/.test(service.id); var titleParts = []; @@ -385,13 +389,16 @@ function createTypesDictionary(docs) { } }); + if (!gapicVersions.includes(gapicVersion)) { + gapicVersions.push(gapicVersion); + } + titleParts = [gapicVersion]; - var nestedTitle = [].slice.call(gapicPath).slice(1, versionIndex); + var nestedTitle = [].slice.call(gapicPath, versionIndex + 1); if (nestedTitle.length > 0) { - nestedTitle = nestedTitle.map(upperFirst).join('/'); - titleParts.push(nestedTitle); + titleParts.push(upperFirst(camel(nestedTitle.join('/')))); } } @@ -403,12 +410,22 @@ function createTypesDictionary(docs) { } } - return { + types.push({ id: id, title: titleParts, contents: contents - }; + }); }); + + gapicVersions.forEach(gapicVersion => { + types.push({ + id: gapicVersion, + title: [gapicVersion], + contents: `${gapicVersion}/index.json` + }); + }); + + return types; } function createToc(types, collapse) { @@ -421,7 +438,8 @@ function createToc(types, collapse) { var protosGroupedByVersion = {}; var services = types - .filter(type => !generatedTypes.includes(type) && !protos.includes(type)) + .filter(type => !generatedTypes.includes(type)) + .filter(type => !protos.includes(type)) .map(function(type) { return { type: type.id, @@ -475,11 +493,12 @@ function createToc(types, collapse) { return titleA < titleB ? -1 : titleA > titleB ? 1 : 0; }); - var parent = generatedTypesGrouped.shift(); + /*jshint loopfunc:true*/ + services = services.filter(service => service.type !== version); var serviceObject = { title: version, - type: parent.id, + type: version, nav: generatedTypesGrouped.map(function(generatedType) { return { title: generatedType.title[generatedType.title.length - 1], @@ -490,7 +509,7 @@ function createToc(types, collapse) { serviceObject.nav.push({ title: 'Data Types', - type: parent.id.replace(/\/\w+_client$/, '/data_types') + type: generatedTypes[0].id.replace(/\/\w+_client$/, '/data_types') }); services.push(serviceObject); From 7b52273d84069e4b190e8c74cd3a8c7ecc9fa29c Mon Sep 17 00:00:00 2001 From: Stephen Sawchuk Date: Fri, 30 Jun 2017 09:00:27 -0400 Subject: [PATCH 15/17] handle other ID types --- scripts/docs/builder.js | 2 +- scripts/docs/parser.js | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/scripts/docs/builder.js b/scripts/docs/builder.js index 4bbc3a408c7..40321bef4f9 100644 --- a/scripts/docs/builder.js +++ b/scripts/docs/builder.js @@ -98,7 +98,7 @@ Builder.prototype.build = function() { var gapicVersions = docs.reduce((grouped, doc) => { - var gapicVersion = doc.id.match(/\/(v[^\/]*)/); + var gapicVersion = doc.id.match(/[/_](v[^\/]*)/); if (gapicVersion) { gapicVersion = gapicVersion[1]; diff --git a/scripts/docs/parser.js b/scripts/docs/parser.js index 6865ee468b0..0ab7a03daad 100644 --- a/scripts/docs/parser.js +++ b/scripts/docs/parser.js @@ -383,7 +383,7 @@ function createTypesDictionary(docs) { var versionIndex; gapicPath.forEach(function(gapicPathPart, index) { - if (/v\d/.test(gapicPathPart)) { + if (/^v\d/.test(gapicPathPart)) { gapicVersion = gapicPathPart; versionIndex = index; } From def35fcf2314570c5efce7712ca278c24bde38d5 Mon Sep 17 00:00:00 2001 From: Stephen Sawchuk Date: Fri, 30 Jun 2017 09:14:18 -0400 Subject: [PATCH 16/17] remove includes usage for older node versions --- package.json | 6 +++--- scripts/docs/builder.js | 7 ++++--- scripts/docs/parser.js | 19 +++++++++++-------- 3 files changed, 18 insertions(+), 14 deletions(-) diff --git a/package.json b/package.json index e0d6b86163f..c021a006351 100644 --- a/package.json +++ b/package.json @@ -2,6 +2,7 @@ "name": "google-cloud-node", "private": "true", "devDependencies": { + "array-includes": "^3.0.3", "array-uniq": "^1.0.3", "async": "^2.0.1", "chalk": "^1.1.3", @@ -15,6 +16,7 @@ "is": "^3.1.0", "jscs": "^2.1.1", "jshint": "^2.9.1", + "lodash.camelcase": "^4.3.0", "lodash.flatten": "^4.3.0", "lodash.template": "^4.3.0", "lodash.upperfirst": "^4.3.1", @@ -27,6 +29,7 @@ "semver": "^5.3.0", "shelljs": "^0.7.3", "string-format-obj": "^1.0.0", + "string-includes": "^2.0.0", "through2": "^2.0.0" }, "scripts": { @@ -72,8 +75,5 @@ "license": "Apache-2.0", "engines": { "node": ">=4.0.0" - }, - "dependencies": { - "lodash.camelcase": "^4.3.0" } } diff --git a/scripts/docs/builder.js b/scripts/docs/builder.js index 40321bef4f9..70c14f6c6a8 100644 --- a/scripts/docs/builder.js +++ b/scripts/docs/builder.js @@ -25,6 +25,7 @@ var globby = require('globby'); var is = require('is'); var path = require('path'); var semver = require('semver'); +var stringIncludes = require('string-includes'); var config = require('./config'); var helpers = require('../helpers'); @@ -104,10 +105,10 @@ Builder.prototype.build = function() { gapicVersion = gapicVersion[1]; mkdir('-p', `${self.dir}/${gapicVersion}`); - if (doc.id.includes('doc_')) { + if (stringIncludes(doc.id, 'doc_')) { grouped[gapicVersion] = grouped[gapicVersion] || []; grouped[gapicVersion].push(doc); - } else if (doc.id.includes('_client')) { + } else if (stringIncludes(doc.id, '_client')) { // Move client file to a separate path. doc.path = `${gapicVersion}/${doc.path}`; self.write(doc.path, doc); @@ -118,7 +119,7 @@ Builder.prototype.build = function() { }, {}); // @TODO delete extra files - docs = docs.filter(doc => !doc.source.includes('doc_')); + docs = docs.filter(doc => !stringIncludes(doc.source, 'doc_')); for (var gapicVersion in gapicVersions) { var gapicFiles = gapicVersions[gapicVersion]; diff --git a/scripts/docs/parser.js b/scripts/docs/parser.js index 0ab7a03daad..dbe992081d3 100644 --- a/scripts/docs/parser.js +++ b/scripts/docs/parser.js @@ -16,6 +16,7 @@ 'use strict'; +var arrayIncludes = require('array-includes'); var camel = require('lodash.camelcase'); var dox = require('dox'); var fs = require('fs'); @@ -24,6 +25,7 @@ var format = require('string-format-obj'); var globby = require('globby'); var path = require('path'); var prop = require('propprop'); +var stringIncludes = require('string-includes'); var template = require('lodash.template'); var upperFirst = require('lodash.upperfirst'); @@ -287,9 +289,9 @@ function createMethod(fileName, parent, block) { .concat(getTagsByType(block, 'property')) .map(createParam); - var isGapic = fileName.includes('doc_'); - var isRequestOrResponse = - name && (name.includes('Request') || name.includes('Response')); + var isGapic = stringIncludes(fileName, 'doc_'); + var isRequestOrResponse = name && + (stringIncludes(name, 'Request') || stringIncludes(name, 'Response')); if (isGapic && isRequestOrResponse) { // Ignore descriptions that have links we don't want, e.g. @@ -389,7 +391,7 @@ function createTypesDictionary(docs) { } }); - if (!gapicVersions.includes(gapicVersion)) { + if (!arrayIncludes(gapicVersions, gapicVersion)) { gapicVersions.push(gapicVersion); } @@ -434,12 +436,12 @@ function createToc(types, collapse) { var toc = extend(true, {}, baseToc); var generatedTypes = types.filter(type => / v\d/.test(type.title.join(' '))); - var protos = types.filter(type => type.id.includes('/doc/')); + var protos = types.filter(type => stringIncludes(type.id, '/doc/')); var protosGroupedByVersion = {}; var services = types - .filter(type => !generatedTypes.includes(type)) - .filter(type => !protos.includes(type)) + .filter(type => !arrayIncludes(generatedTypes, type)) + .filter(type => !arrayIncludes(protos, type)) .map(function(type) { return { type: type.id, @@ -516,7 +518,8 @@ function createToc(types, collapse) { } } - services = services.filter(service => !service.type.includes('data_types')); + services = services + .filter(service => !stringIncludes(service.type, 'data_types')); if (!collapse) { toc.services = services; From 8146d6a7eeb954b7d89c3ef8b413c316a4d20414 Mon Sep 17 00:00:00 2001 From: Stephen Sawchuk Date: Fri, 30 Jun 2017 09:24:22 -0400 Subject: [PATCH 17/17] remove snippet tests from generated docs --- test/docs.js | 2 ++ 1 file changed, 2 insertions(+) diff --git a/test/docs.js b/test/docs.js index a267202362d..295e8ca3aec 100644 --- a/test/docs.js +++ b/test/docs.js @@ -246,6 +246,8 @@ function getDocs(mod) { return glob .sync('docs/json/' + mod + '/*/*.json', { ignore: [ + '**/doc_*.json', + '**/*_client.json', '**/toc.json', '**/types.json' ]