Skip to content

doc.go template

Stephen Tramer edited this page Sep 17, 2018 · 4 revisions

The following is a template that you can use for making doc.go files at the package level. doc.go files should be at the root of the appropriate package, and not part of a service version. For example:

  • services/keyvault/doc.go
  • services/keyvault/mgmt/doc.go

The general format of the file should be the same throughout, and there is some required text, but the following placeholders are used:

  • _SERVICE_OVERVIEW_ is a short overview of the service. This should include the marketing name of the service as part of the opening (for example, Azure Key Vault, Azure Storage, Azure Monitoring) and subsequent usages can drop branding, use common acronyms, etc. When in doubt follow the Cloud Style Guide.
  • _FULL_SERVICE_NAME_ is the full branded/marketing name of the service (for example, Azure Key Vault)
  • _TITLE_i_ is the title of the published article linked to.
  • _LINK_i_ is an https link to a document on docs.microsoft.com. This link must not include a locale.
  • _EXAMPLE_NAME_ is a descriptive name for the package example.
  • _EXAMPLE_TEXT_ is the full text describing the following example.
  • _EXAMPLE_CODE_ is the full code for the example. This code does not have to be cut-and-paste executable. However it should make dependencies clear either through arguments provided to a function, comments explaining object types, and descriptive names of called functions.
  • _SAMPLES_LINK_ is a link to a subdirectory of https://github.com/azure-samples/azure-sdk-for-go-samples for the service. If no samples exist for the package, do not include this section.
  • _PACKAGE_NAME_ is the name of the package.

NOTE: You may link up to 5 documents on the docs site. It's recommended to link at least an overview, an 'about' for any complex concepts, and a quickstart/howto. If there is a Go-specific document on the site for the service, definitely link to it here.

// Copyright (c) Microsoft and contributors.  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.

/*
	_SERVICE_OVERVIEW_

	You can learn more about _FULL_SERVICE_NAME_ on the Microsoft documentation site:

		- _TITLE_1_: _LINK_1_
		- _TITLE_2_: _LINK_2_
		- ...
		- _TITLE_N_: _LINK_N_

	[max(N) == 5]

	Example - _EXAMPLE_NAME_

	_EXAMPLE_TEXT_

		_EXAMPLE_CODE_

	Samples

	You can see all of the available samples for _FULL_SERVICE_NAME_ by browsing our samples repository. All samples are runnable through go test.
		_SAMPLES_LINK_

	Contribute

	We encourage and welcome contributions to the Azure SDK for Go. The best ways to help us out are:

	    - File an issue on github: https://github.com/azure/azure-sdk-for-go/issues
	    - Contribute a pull request: https://github.com/Azure/azure-sdk-for-go/blob/master/CONTRIBUTING.md

	All Microsoft open source projects follow a standard Code of Conduct. You can learn more about our CoC at
	https://opensource.microsoft.com/codeofconduct/
*/
package _PACKAGE_NAME_
Clone this wiki locally