Merge pull request #921 from timofurrer/docs/descriptions

Improve documentation and reference upstream API for every data source and resource

Author: timofurrer

docs/data-sources/branch.md

@@ -3,12 +3,15 @@
 page_title: "gitlab_branch Data Source - terraform-provider-gitlab"
 subcategory: ""
 description: |-
-  Provide details about a gitlab project branch
+  The gitlab_branch data source allows details of a repository branch to be retrieved by its name and project.
+  Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/branches.html#get-single-repository-branch
 ---
 
 # gitlab_branch (Data Source)
 
-Provide details about a gitlab project branch
+The `gitlab_branch` data source allows details of a repository branch to be retrieved by its name and project.
+
+**Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ee/api/branches.html#get-single-repository-branch)
 
 ## Example Usage
 

docs/data-sources/group.md

@@ -3,15 +3,15 @@
 page_title: "gitlab_group Data Source - terraform-provider-gitlab"
 subcategory: ""
 description: |-
-  Provide details about a specific group in the gitlab provider.
-  Note: exactly one of groupid or fullpath must be provided.
+  The gitlab_group data source allows details of a group to be retrieved by its id or full path.
+  Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/groups.html#details-of-a-group
 ---
 
 # gitlab_group (Data Source)
 
-Provide details about a specific group in the gitlab provider.
+The `gitlab_group` data source allows details of a group to be retrieved by its id or full path.
 
-> **Note**: exactly one of group_id or full_path must be provided.
+**Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ee/api/groups.html#details-of-a-group)
 
 ## Example Usage
 

docs/data-sources/group_membership.md

@@ -3,15 +3,15 @@
 page_title: "gitlab_group_membership Data Source - terraform-provider-gitlab"
 subcategory: ""
 description: |-
-  Provide details about a list of group members in the gitlab provider. The results include id, username, name and more about the requested members.
-  Note: exactly one of groupid or fullpath must be provided.
+  The gitlab_group_membership data source allows to list and filter all members of a group specified by either its id or full path.
+  Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/members.html#list-all-members-of-a-group-or-project
 ---
 
 # gitlab_group_membership (Data Source)
 
-Provide details about a list of group members in the gitlab provider. The results include id, username, name and more about the requested members.
+The `gitlab_group_membership` data source allows to list and filter all members of a group specified by either its id or full path.
 
-> **Note**: exactly one of group_id or full_path must be provided.
+**Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ee/api/members.html#list-all-members-of-a-group-or-project)
 
 ## Example Usage
 

docs/data-sources/project.md

@@ -3,12 +3,15 @@
 page_title: "gitlab_project Data Source - terraform-provider-gitlab"
 subcategory: ""
 description: |-
-  Provide details about a specific project in the gitlab provider. The results include the name of the project, path, description, default branch, etc.
+  The gitlab_project data source allows details of a project to be retrieved by either its ID or its path with namespace.
+  Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/projects.html#get-single-project
 ---
 
 # gitlab_project (Data Source)
 
-Provide details about a specific project in the gitlab provider. The results include the name of the project, path, description, default branch, etc.
+The `gitlab_project` data source allows details of a project to be retrieved by either its ID or its path with namespace.
+
+**Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ee/api/projects.html#get-single-project)
 
 ## Example Usage
 

docs/data-sources/project_protected_branch.md

@@ -3,12 +3,15 @@
 page_title: "gitlab_project_protected_branch Data Source - terraform-provider-gitlab"
 subcategory: ""
 description: |-
-  Provides details about a specific protected branch in a given project.
+  The gitlab_protected_branch data source allows details of a protected branch to be retrieved by its name and the project it belongs to.
+  Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/protected_branches.html#get-a-single-protected-branch-or-wildcard-protected-branch
 ---
 
 # gitlab_project_protected_branch (Data Source)
 
-Provides details about a specific protected branch in a given project.
+The `gitlab_protected_branch` data source allows details of a protected branch to be retrieved by its name and the project it belongs to.
+
+**Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ee/api/protected_branches.html#get-a-single-protected-branch-or-wildcard-protected-branch)
 
 ## Example Usage
 

docs/data-sources/project_protected_branches.md

@@ -3,12 +3,15 @@
 page_title: "gitlab_project_protected_branches Data Source - terraform-provider-gitlab"
 subcategory: ""
 description: |-
-  Provides details about all protected branches in a given project.
+  The gitlab_protected_branches data source allows details of the protected branches of a given project.
+  Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/protected_branches.html#list-protected-branches
 ---
 
 # gitlab_project_protected_branches (Data Source)
 
-Provides details about all protected branches in a given project.
+The `gitlab_protected_branches` data source allows details of the protected branches of a given project.
+
+**Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ee/api/protected_branches.html#list-protected-branches)
 
 ## Example Usage
 

docs/data-sources/projects.md

@@ -3,18 +3,21 @@
 page_title: "gitlab_projects Data Source - terraform-provider-gitlab"
 subcategory: ""
 description: |-
-  Provide details about a list of projects in the Gitlab provider. Listing all projects and group projects with project filtering https://docs.gitlab.com/ee/api/projects.html#list-user-projects or group project filtering https://docs.gitlab.com/ee/api/groups.html#list-a-groups-projects is supported.
-  NOTE: This data source supports all available filters exposed by the xanzy/go-gitlab package, which might not expose all available filters exposed by the Gitlab APIs.
-  NOTE: The owner sub-attributes are only populated if the Gitlab token used has an administrator scope.
+  The gitlab_projects data source allows details of multiple projects to be retrieved. Optionally filtered by the set attributes.
+  -> This data source supports all available filters exposed by the xanzy/go-gitlab package, which might not expose all available filters exposed by the Gitlab APIs.
+  -> The owner sub-attributes are only populated if the Gitlab token used has an administrator scope.
+  Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/projects.html#list-all-projects
 ---
 
 # gitlab_projects (Data Source)
 
-Provide details about a list of projects in the Gitlab provider. Listing all projects and group projects with [project filtering](https://docs.gitlab.com/ee/api/projects.html#list-user-projects) or [group project filtering](https://docs.gitlab.com/ee/api/groups.html#list-a-groups-projects) is supported.
+The `gitlab_projects` data source allows details of multiple projects to be retrieved. Optionally filtered by the set attributes.
 
-> **NOTE**: This data source supports all available filters exposed by the `xanzy/go-gitlab` package, which might not expose all available filters exposed by the Gitlab APIs.
+-> This data source supports all available filters exposed by the xanzy/go-gitlab package, which might not expose all available filters exposed by the Gitlab APIs.
 
-> **NOTE**: The [owner sub-attributes](#nestedobjatt--projects--owner) are only populated if the Gitlab token used has an administrator scope.
+-> The [owner sub-attributes](#nestedobjatt--projects--owner) are only populated if the Gitlab token used has an administrator scope.
+
+**Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ee/api/projects.html#list-all-projects)
 
 ## Example Usage
 

docs/data-sources/user.md

@@ -3,15 +3,18 @@
 page_title: "gitlab_user Data Source - terraform-provider-gitlab"
 subcategory: ""
 description: |-
-  Provide details about a specific user in the gitlab provider. Especially the ability to lookup the id for linking to other resources.
-  -> Some attributes might not be returned depending on if you're an admin or not. Please refer to Gitlab documentation https://docs.gitlab.com/ce/api/users.html#single-user for more details.
+  The gitlab_user data source allows details of a user to be retrieved by either the user ID, username or email address.
+  -> Some attributes might not be returned depending on if you're an admin or not.
+  Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/users.html#single-user
 ---
 
 # gitlab_user (Data Source)
 
-Provide details about a specific user in the gitlab provider. Especially the ability to lookup the id for linking to other resources.
+The `gitlab_user` data source allows details of a user to be retrieved by either the user ID, username or email address.
 
--> Some attributes might not be returned depending on if you're an admin or not. Please refer to [Gitlab documentation](https://docs.gitlab.com/ce/api/users.html#single-user) for more details.
+-> Some attributes might not be returned depending on if you're an admin or not.
+
+**Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ee/api/users.html#single-user)
 
 ## Example Usage
 

docs/data-sources/users.md

@@ -3,15 +3,21 @@
 page_title: "gitlab_users Data Source - terraform-provider-gitlab"
 subcategory: ""
 description: |-
-  Provide details about a list of users in the gitlab provider. The results include id, username, email, name and more about the requested users. Users can also be sorted and filtered using several options.
-  NOTE: Some available options require administrator privileges. Please visit [Gitlab API documentation][usersforadmins] for more information.
+  The gitlab_users data source allows details of multiple users to be retrieved given some optional filter criteria.
+  -> Some attributes might not be returned depending on if you're an admin or not.
+  -> Some available options require administrator privileges.
+  Upstream API: GitLab REST API docs https://docs.gitlab.com/ce/api/users.html#list-users
 ---
 
 # gitlab_users (Data Source)
 
-Provide details about a list of users in the gitlab provider. The results include id, username, email, name and more about the requested users. Users can also be sorted and filtered using several options.
+The `gitlab_users` data source allows details of multiple users to be retrieved given some optional filter criteria.
 
-**NOTE**: Some available options require administrator privileges. Please visit [Gitlab API documentation][users_for_admins] for more information.
+-> Some attributes might not be returned depending on if you're an admin or not.
+
+-> Some available options require administrator privileges.
+
+**Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ce/api/users.html#list-users)
 
 ## Example Usage
 

docs/index.md

@@ -9,6 +9,12 @@ Use the GitLab provider to interact with GitLab resources, like
 users, groups, projects and more. You must configure the provider with
 the proper credentials before you can use it.
 
+The provider uses the [`xanzy/go-gitlab`](https://github.com/xanzy/go-gitlab) library
+to interact with the [GitLab REST API](https://docs.gitlab.com/ee/api/api_resources.html).
+
+Each data source and resource references the appropriate upstream GitLab REST API documentation,
+which may be consumed to better understand the behavior of the API.
+
 Use the navigation to the left to read about the valid data sources and resources.
 
 This provider requires at least [Terraform 0.12](https://www.terraform.io/downloads.html).