docs: Add package documentation

Author: UnseenWizzard

api/auth/oauth.go

@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package auth simplifies creating token and oAuth authenticated http.Client for use with rest.Client
 package auth
 
 import (

api/clients/automation/automation.go

@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+// Package automation (api/clients/automation) provides a simple CRUD client for the Automations API.
+// For a 'smart' API client see package clients/automation.
 package automation
 
 import (

api/clients/buckets/bucket.go

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package buckets (api/clients/buckets) provides a simple CRUD client for the Grail Bucket API.
+// For a 'smart' API client see package clients/buckets.
 package buckets
 
 import (

api/clients/doc.go

@@ -0,0 +1,30 @@
+// @license
+// Copyright 2023 Dynatrace 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.
+
+/*
+Package clients contains simple CRUD clients for the Dynatrace API.
+
+For 'smarter' clients with extended functionality see package [github.com/dynatrace/dynatrace-configuration-as-code-core/clients].
+
+In general, the CRUD clients make a single API call per operation, but in some cases may make several if the Dynatrace API requires it.
+
+Clients implement the following methods:
+
+  - Get
+  - List
+  - Create
+  - Update
+  - Delete
+*/
+package clients

api/doc.go

@@ -0,0 +1,23 @@
+// @license
+// Copyright 2023 Dynatrace 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.
+
+/*
+Package api groups packages simplifying Dynatrace API access.
+
+Notably it contains the following packages
+  - [github.com/dynatrace/dynatrace-configuration-as-code-core/api/rest] containing an extended rest client with optional features like rate-limiting, request logging, etc.
+  - [github.com/dynatrace/dynatrace-configuration-as-code-core/api/auth] containing methods for creating authenticated rest clients
+  - [github.com/dynatrace/dynatrace-configuration-as-code-core/api/clients] containing client implementations for specific Dynatrace APIs
+*/
+package api

api/rest/client.go

@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package rest provides an extended rest.Client with optional behaviours like rate limiting, request/response logging, etc.
 package rest
 
 import (

clients/doc.go

@@ -0,0 +1,39 @@
+// @license
+// Copyright 2023 Dynatrace 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.
+
+/*
+Package clients contains 'smart' clients for the Dynatrace API.
+
+These clients are generally based on those found in package api/clients, but implement logic to ensure the Dynatrace API
+can be used for configuration-as-code use-cases reliably.
+
+For the underlying clients see package [github.com/dynatrace/dynatrace-configuration-as-code-core/api/clients].
+
+In general, whereas the CRUD api/clients make a single API call per operation, the ones in this package make several and
+react to API responses as needed.
+
+For example, the clients in this package will resolve and follow pagination in their List methods, whereas an api/clients
+implementation requires/allows the user to handle pagination and make several requests on their own.
+
+Clients implement the following methods:
+  - Get
+  - List
+  - Create
+  - Update
+  - Upsert (Create or Update as needed)
+  - Delete
+
+A clients.Factory simplifies creation of clients.
+*/
+package clients