Improve documentation

doc/api/pipelines.md

@@ -14,11 +14,11 @@ GET /projects/:id/pipelines
 | `scope`   | string  | no       | The scope of pipelines, one of: `running`, `pending`, `finished`, `branches`, `tags` |
 | `status`  | string  | no       | The status of pipelines, one of: `running`, `pending`, `success`, `failed`, `canceled`, `skipped` |
 | `ref`     | string  | no       | The ref of pipelines |
-| `yaml_errors`| boolean  | no       | Returns pipelines which have an error of gitlab-ci.yml |
+| `yaml_errors`| boolean  | no       | Returns pipelines with invalid configurations |
 | `name`| string  | no       | The name of the user who triggered pipelines |
 | `username`| string  | no       | The username of the user who triggered pipelines |
-| `order_by`| string  | no       | Return requests ordered by `id`, `status`, `ref`, or `user_id`. Default is `id`. Can be combined with `sort`. If you omit `sort`, its default value is used (`desc`) |
-| `sort`    | string  | no       | Return requests sorted in `asc` or `desc` order. Default is `desc`. Can be combined with `order_by`. If you omit `order_by`, its default value is used (`id`) |
+| `order_by`| string  | no       | Order pipelines by `id`, `status`, `ref`, or `user_id` (default: `id`) |
+| `sort`    | string  | no       | Sort pipelines in `asc` or `desc` order (default: `desc`) |
 
 ```
 curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/pipelines"

lib/api/pipelines.rb

@@ -19,13 +19,13 @@ module API
         optional :status,   type: String, values: HasStatus::AVAILABLE_STATUSES,
                             desc: 'The status of pipelines'
         optional :ref,      type: String, desc: 'The ref of pipelines'
-        optional :yaml_errors, type: Boolean, desc: 'If true, returns only yaml error pipelines'
-        optional :name,     type: String, desc: 'The name of user who triggered pipelines'
-        optional :username, type: String, desc: 'The username of user who triggered pipelines'
+        optional :yaml_errors, type: Boolean, desc: 'Returns pipelines with invalid configurations'
+        optional :name,     type: String, desc: 'The name of the user who triggered pipelines'
+        optional :username, type: String, desc: 'The username of the user who triggered pipelines'
         optional :order_by, type: String, values: PipelinesFinder::ALLOWED_INDEXED_COLUMNS, default: 'id',
-                            desc: 'The order_by which is combined with a sort'
+                            desc: 'Order pipelines'
         optional :sort,     type: String, values: %w[asc desc], default: 'desc',
-                            desc: 'The sort method which is combined with an order_by'
+                            desc: 'Sort pipelines'
       end
       get ':id/pipelines' do
         authorize! :read_pipeline, user_project