The Big Public API Documentation Update, volume 3. (#196)

* Rework and update getting-started.md

* Reword parts of the API docs in annotations.dart

* Add description of path resolution behavior in requests.md
This commit addresses issue #195

* Reword parts of the documentations in requests.md

* Reword the error handling description in getting-started.md

* Reword and update most of the documentation in requests.md

* Add missing @s to annotation mentions in getting-started.md

* Remove an unnecessary new line from getting-started.md

* Add further explanation to an example service's create method in getting-started.md

* Update the README of chopper_built_value

* Update the README of chopper_generator

* Update and reword top level README.md and chopper/README.md

* Try to fix text formatting in requests.md

* Fix wording requests.md's form URL encoded section

* Remove unsafe hint on build_runner from getting-started.md

README.md

@@ -1,34 +1,23 @@
----
-description: Chopper is an http client generator using source_gen and inspired by Retrofit.
----
-
 # Chopper
 
 [![pub package](https://img.shields.io/pub/v/chopper.svg)](https://pub.dartlang.org/packages/chopper) [![Build Status](https://travis-ci.com/lejard-h/chopper.svg?branch=master)](https://travis-ci.com/lejard-h/chopper.svg?branch=master) [![codecov](https://codecov.io/gh/lejard-h/chopper/branch/master/graph/badge.svg)](https://codecov.io/gh/lejard-h/chopper)
 
-[Documentations](https://hadrien-lejard.gitbook.io/chopper)
-
-## Installation
+Chopper is an http client generator for Dart and Flutter using source_gen and inspired by Retrofit.
 
-```yaml
-# pubspec.yaml
+[Documentation](https://hadrien-lejard.gitbook.io/chopper)
 
-dependencies:
-  chopper: ^3.0.2
+## Installation
 
-dev_dependencies:
-  build_runner: ^1.0.0
-  chopper_generator: ^3.0.4
-```
+Please refer to the installation guide at [pub.dev](https://pub.dev/packages/chopper/install) or in the [Getting started](getting-started.md) document.
 
-* [Getting started](getting-started.md)
+* [Requests](requests.md)
 * [Converters](converters/converters.md)
 * [Interceptors](interceptors.md)
 
 ## Examples
 
-* [Json serializable](https://github.com/lejard-h/chopper/blob/master/example/bin/main_json_serializable.dart)
-* [Built Value](https://github.com/lejard-h/chopper/blob/master/example/bin/main_built_value.dart)
+* [json serializable Converter](https://github.com/lejard-h/chopper/blob/master/example/bin/main_json_serializable.dart)
+* [built value Converter](https://github.com/lejard-h/chopper/blob/master/example/bin/main_built_value.dart)
 * [Angular](https://github.com/lejard-h/chopper/blob/master/example/web/main.dart)
 
 ## [Issue Tracker](https://github.com/lejard-h/chopper/issues)

chopper/README.md

@@ -2,6 +2,8 @@
 
 [![pub package](https://img.shields.io/pub/v/chopper.svg)](https://pub.dartlang.org/packages/chopper) [![Build Status](https://travis-ci.com/lejard-h/chopper.svg?branch=master)](https://travis-ci.org/lejard-h/chopper) [![codecov](https://codecov.io/gh/lejard-h/chopper/branch/master/graph/badge.svg)](https://codecov.io/gh/lejard-h/chopper)
 
+Chopper is an http client generator for Dart and Flutter using source_gen and inspired by Retrofit.
+
 [**Documentation**](https://hadrien-lejard.gitbook.io/chopper)
 
 ## Adding Chopper to your project
@@ -37,9 +39,9 @@ Latest versions:
 
 ## Examples
 
-* [Json serializable](https://github.com/lejard-h/chopper/blob/master/example/bin/main_json_serializable.dart)
-* [Built Value](https://github.com/lejard-h/chopper/blob/master/example/bin/main_built_value.dart)
+* [json_serializable Converter](https://github.com/lejard-h/chopper/blob/master/example/bin/main_json_serializable.dart)
+* [built_value Converter](https://github.com/lejard-h/chopper/blob/master/example/bin/main_built_value.dart)
 * [Angular](https://github.com/lejard-h/chopper/blob/master/example/web/main.dart)
 
-## If you encounter any issues, or need a feature implemented, please visit [Chopper's Issue Tracker](https://github.com/lejard-h/chopper/issues).
+## If you encounter any issues, or need a feature implemented, please visit [Chopper's Issue Tracker on GitHub](https://github.com/lejard-h/chopper/issues).
 

chopper/lib/src/annotations.dart

@@ -20,7 +20,7 @@ import 'constants.dart';
 /// See [Method] to define an HTTP request
 @immutable
 class ChopperApi {
-  /// Url that will prefix every request define inside that API.
+  /// A part of a URL that every request defined inside a class annotated with [ChopperApi] will be prefixed with.
   final String baseUrl;
 
   const ChopperApi({
@@ -43,7 +43,7 @@ class ChopperApi {
 @immutable
 class Path {
   /// Name is used to bind a method parameter to
-  /// the url parameter.
+  /// a URL path parameter.
   /// ```dart
   /// @Get(path: '/{param}')
   /// Future<Response> fetch(@Path('param') String hello);

chopper_built_value/README.md

@@ -1 +1 @@
-[Chopper](https://github.com/lejard-h/chopper) is an http client generator using source_gen, inspired by Retrofit.
+This package provides a Converter based on built_value that can be used with [Chopper](https://github.com/lejard-h/chopper) to convert objects to JSON and vice versa.

chopper_generator/README.md

@@ -1 +1 @@
-[Chopper](https://github.com/lejard-h/chopper) is an http client generator using source_gen, inspired by Retrofit.
+This package provides the code generator for the [Chopper](https://github.com/lejard-h/chopper) package.

getting-started.md

@@ -1,68 +1,92 @@
 # Getting started
 
-## How it works ?
+## How does Chopper work?
 
-Due to Dart limitation on Flutter and Web browser, Chopper does not use reflection but code generation with the help of the [build](https://pub.dev/packages/build) and [source\_gen](https://pub.dev/packages/source_gen) packages from the Dart Team.
+Due to limitations to Dart on Flutter and the Web browser, Chopper doesn't use reflection but code generation with the help of the [build](https://pub.dev/packages/build) and [source\_gen](https://pub.dev/packages/source_gen) packages from the Dart Team.
 
 ## Installation
 
-First you need to add `chopper` and `chopper_generator` to your project dependencies.
+Add the `chopper` and the `chopper_generator` packages to your project dependencies.
 
 ```yaml
 # pubspec.yaml
 
 dependencies:
-  chopper: ^2.0.0
+  chopper: ^3.0.7
 
 dev_dependencies:
   build_runner: ^1.0.0
-  chopper_generator: ^2.0.0
+  chopper_generator: ^3.0.7
 ```
 
-And run `pub get`
+Run `pub get` to start using Chopper in your project.
 
 ## Define your API
 
 ### ChopperApi
 
-To define a client, use the `ChopperApi` annotation on a class and extends the `ChopperService` client.
+To define a client, use the `@
+ChopperApi` annotation on an abstract class that extends the `ChopperService` class.
 
 ```dart
 // YOUR_FILE.dart
 
 import "dart:async";
 import 'package:chopper/chopper.dart';
 
-// this is necessary for the generated code to find your class
+// This is necessary for the generator to work.
 part "YOUR_FILE.chopper.dart";
 
 @ChopperApi(baseUrl: "/todos")
 abstract class TodosListService extends ChopperService {
 
-  // helper methods that help you instantiate your service
+  // A helper method that helps instantiating the service. You can omit this method and use the generated class directly instead.
   static TodosListService create([ChopperClient client]) => 
       _$TodosListService(client);
 }
 ```
 
-`ChopperApi` annotation takes one optional parameter, the `baseUrl` that will prefix all the request define in the class.
+The `@ChopperApi` annotation takes one optional parameter - the `baseUrl` - that will prefix all the request's URLs defined in the class.
 
-### Define a request
+> There's an exception from this behavior described in the [Requests](requests.md) section of the documentation.
 
-To define a request, use one of the following annotations `Get`, `Post`, `Put`, `Patch`, `Delete` and must return a `Future<Response>`
+### Defining a request
 
-Let's say you want to do a `GET` request on the following endpoint `/todos/TODO_ID`, add the following method declaration to your class.
+Use one of the following annotations on abstract methods of a service class to define requests:
+
+* `@Get` 
+
+* `@Post` 
+
+* `@Put`
+
+* `@Patch`
+
+* `@Delete`
+
+* `@Head`
+
+Request methods must return with values of the type `Future<Response>` or `Future<Response<SomeType>>`.
+
+To define a `GET` request to the endpoint `/todos` in the service class above, add one of the following method declarations to the class:
+
+```dart
+@Get()
+Future<Response> getTodos();
+```
+
+or
 
 ```dart
-@Get(path: '/{id}')
-Future<Response> getTodo(@Path() String id);
+@Get()
+Future<Response<List<Todo>>> getTodos();
 ```
 
-Using `{id}` and the `Path` annotation your are telling chopper to replace `{id}` in the url by the value of the `id` parameter.
+URL manipulation with dynamic path, and query parameters is also supported. To learn more about URL manipulation with Chopper, have a look at the [Requests](requests.md) section of the documentation. 
 
-## ChopperClient
+## Defining a ChopperClient
 
-After defining your `ChopperService` you need to attribute a `ChopperClient` to it. The `ChopperClient` will manage the server hostname to call and can handle multiple `ChopperService`. It is also responsible of applying [interceptors](interceptors.md) and [converter]() to your requests.
+After defining one or more `ChopperService`s, you need to bind instances of them to a `ChopperClient`. The `ChopperClient` provides the base URL for every service and it is also responsible for applying [interceptors](interceptors.md) and [converters](converters/converters.md) on the requests it handles.
 
 ```dart
 import "dart:async";
@@ -74,36 +98,28 @@ void main() async {
   final chopper = ChopperClient(
       baseUrl: "http://my-server:8000",
       services: [
-        // inject the generated service
+        // Create and pass an instance of the generated service to the client
         TodosListService.create()
       ],
     );
 
-  /// retrieve your service
+  /// Get a reference to the client-bound service instance...
   final todosService = chopper.getService<TodosListService>();
-  /// or create a new one
-  final todosService = TodosListService.create(chopper);
+  /// ... or create a new instance by explicitly binding it to a client.
+  final anotherTodosService = TodosListService.create(chopper);
 
-  /// then call your function
-  final response = await todosService.getTodosList();
+  /// Making a request is as easy as calling a function of the service.
+  final response = await todosService.getTodos();
   
   if (response.isSuccessful) {
-    // successful request
+    // Successful request
     final body = response.body;
   } else {
-    // error from server
+    // Error code received from server
     final code = response.statusCode;
     final error = response.error;
   }
 }
-
 ```
 
-
-
-### 
-
-
-
-
-
+Handling I/O and other exceptions should be done by surrounding requests with `try-catch` blocks.