diff options
Diffstat (limited to 'crates/secd/proto/google/api/documentation.proto')
| -rw-r--r-- | crates/secd/proto/google/api/documentation.proto | 157 |
1 files changed, 157 insertions, 0 deletions
diff --git a/crates/secd/proto/google/api/documentation.proto b/crates/secd/proto/google/api/documentation.proto new file mode 100644 index 0000000..03cd731 --- /dev/null +++ b/crates/secd/proto/google/api/documentation.proto @@ -0,0 +1,157 @@ +// Copyright 2018 Google LLC. +// +// 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. + +syntax = "proto3"; + +package google.api; + +option go_package = "google.golang.org/genproto/googleapis/api/serviceconfig;serviceconfig"; +option java_multiple_files = true; +option java_outer_classname = "DocumentationProto"; +option java_package = "com.google.api"; +option objc_class_prefix = "GAPI"; + + +// `Documentation` provides the information for describing a service. +// +// Example: +// <pre><code>documentation: +// summary: > +// The Google Calendar API gives access +// to most calendar features. +// pages: +// - name: Overview +// content: (== include google/foo/overview.md ==) +// - name: Tutorial +// content: (== include google/foo/tutorial.md ==) +// subpages; +// - name: Java +// content: (== include google/foo/tutorial_java.md ==) +// rules: +// - selector: google.calendar.Calendar.Get +// description: > +// ... +// - selector: google.calendar.Calendar.Put +// description: > +// ... +// </code></pre> +// Documentation is provided in markdown syntax. In addition to +// standard markdown features, definition lists, tables and fenced +// code blocks are supported. Section headers can be provided and are +// interpreted relative to the section nesting of the context where +// a documentation fragment is embedded. +// +// Documentation from the IDL is merged with documentation defined +// via the config at normalization time, where documentation provided +// by config rules overrides IDL provided. +// +// A number of constructs specific to the API platform are supported +// in documentation text. +// +// In order to reference a proto element, the following +// notation can be used: +// <pre><code>[fully.qualified.proto.name][]</code></pre> +// To override the display text used for the link, this can be used: +// <pre><code>[display text][fully.qualified.proto.name]</code></pre> +// Text can be excluded from doc using the following notation: +// <pre><code>(-- internal comment --)</code></pre> +// +// A few directives are available in documentation. Note that +// directives must appear on a single line to be properly +// identified. The `include` directive includes a markdown file from +// an external source: +// <pre><code>(== include path/to/file ==)</code></pre> +// The `resource_for` directive marks a message to be the resource of +// a collection in REST view. If it is not specified, tools attempt +// to infer the resource from the operations in a collection: +// <pre><code>(== resource_for v1.shelves.books ==)</code></pre> +// The directive `suppress_warning` does not directly affect documentation +// and is documented together with service config validation. +message Documentation { + // A short summary of what the service does. Can only be provided by + // plain text. + string summary = 1; + + // The top level pages for the documentation set. + repeated Page pages = 5; + + // A list of documentation rules that apply to individual API elements. + // + // **NOTE:** All service configuration rules follow "last one wins" order. + repeated DocumentationRule rules = 3; + + // The URL to the root of documentation. + string documentation_root_url = 4; + + // Declares a single overview page. For example: + // <pre><code>documentation: + // summary: ... + // overview: (== include overview.md ==) + // </code></pre> + // This is a shortcut for the following declaration (using pages style): + // <pre><code>documentation: + // summary: ... + // pages: + // - name: Overview + // content: (== include overview.md ==) + // </code></pre> + // Note: you cannot specify both `overview` field and `pages` field. + string overview = 2; +} + +// A documentation rule provides information about individual API elements. +message DocumentationRule { + // The selector is a comma-separated list of patterns. Each pattern is a + // qualified name of the element which may end in "*", indicating a wildcard. + // Wildcards are only allowed at the end and for a whole component of the + // qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". To + // specify a default for all applicable elements, the whole pattern "*" + // is used. + string selector = 1; + + // Description of the selected API(s). + string description = 2; + + // Deprecation description of the selected element(s). It can be provided if an + // element is marked as `deprecated`. + string deprecation_description = 3; +} + +// Represents a documentation page. A page can contain subpages to represent +// nested documentation set structure. +message Page { + // The name of the page. It will be used as an identity of the page to + // generate URI of the page, text of the link to this page in navigation, + // etc. The full page name (start from the root page name to this page + // concatenated with `.`) can be used as reference to the page in your + // documentation. For example: + // <pre><code>pages: + // - name: Tutorial + // content: (== include tutorial.md ==) + // subpages: + // - name: Java + // content: (== include tutorial_java.md ==) + // </code></pre> + // You can reference `Java` page using Markdown reference link syntax: + // `[Java][Tutorial.Java]`. + string name = 1; + + // The Markdown content of the page. You can use <code>(== include {path} ==)</code> + // to include content from a Markdown file. + string content = 2; + + // Subpages of this page. The order of subpages specified here will be + // honored in the generated docset. + repeated Page subpages = 3; +} |