The Big Public API Documentation update, volume 2. (#193)

* Update the documentation of BuiltValueConverter

* Update the documentation and usage guide of BuiltValueConverter

* Update description texts in pubspec.yaml files

* Change homepage tag to documentation in chopper/pubspec.yaml

* Change homepage tag to documentation in chopper_built_value/pubspec.yaml and make it point to its actual documentation page

* Change homepage tag to documentation in chopper_generator/pubspec.yaml

* Change homepage tag to documentation in chopper/example/pubspec.yaml and make it point to the actual documentation

* Fix wording in chopper_generator/README.md

* Fix wording in chopper_built_value/README.md

* Fix HTML escape sequences escaping into markdown and inline docs; Fix code sample syntax errors in some docs

Those pesky escapists.

* Add dynamic version tag to built-value-converter.md

* Fix typo in the package name in the installation section of built-value-converter.md

* Fix typo in built-value-converter.md

* Reorganize and update chopper/README.md

chopper/README.md

@@ -2,21 +2,35 @@
 
 [![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)
 
-[Documentations](https://hadrien-lejard.gitbook.io/chopper)
+[**Documentation**](https://hadrien-lejard.gitbook.io/chopper)
 
-## Installation
+## Adding Chopper to your project
+
+In your project's `pubspec.yaml` file, 
+
+* Add *chopper*'s latest version to your *dependencies*.
+* Add `build_runner: ^1.10.3` to your *dev_dependencies*.
+  * *build_runner* may already be in your *dev_dependencies* depending on your project setup and other dependencies.
+* Add *chopper_generator*'s latest version to your *dev_dependencies*.
 
 ```yaml
 # pubspec.yaml
 
 dependencies:
-  chopper: ^2.0.0
+  chopper: ^<latest version>
 
 dev_dependencies:
-  build_runner: ^1.0.0
-  chopper_generator: ^2.0.0
+  build_runner: ^1.10.3
+  chopper_generator: ^<latest version>
 ```
 
+Latest versions:
+
+* *chopper* ![pub package](https://img.shields.io/pub/v/chopper.svg) 
+* *chopper_generator* ![pub package](https://img.shields.io/pub/v/chopper_generator.svg) 
+
+## Documentation
+
 * [Getting started](getting-started.md)
 * [Converters](converters/converters.md)
 * [Interceptors](interceptors.md)
@@ -27,5 +41,5 @@ dev_dependencies:
 * [Built Value](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)
+## If you encounter any issues, or need a feature implemented, please visit [Chopper's Issue Tracker](https://github.com/lejard-h/chopper/issues).
 

chopper/lib/src/base.dart

@@ -39,7 +39,7 @@ class ChopperClient {
 
   /// The [ErrorConverter] that handles response transformation before the
   /// response interceptors are called, but only on error responses
-  /// \(statusCode < 200 || statusCode >= 300\).
+  /// (statusCode < 200 || statusCode >= 300\).
   final ErrorConverter errorConverter;
 
   final Map<Type, ChopperService> _services = {};

chopper/lib/src/interceptor.dart

@@ -85,7 +85,7 @@ abstract class Converter {
   /// \(e.g., `String` or `CustomObject)`.
   ///
   /// If `BodyType` is a `List` or a `BuiltList`, `InnerType` is the type of the
-  /// generic parameter \(e.g., `convertResponse<List<CustomObject>, CustomObject>(response)` \).
+  /// generic parameter (e.g., `convertResponse<List<CustomObject>, CustomObject>(response)` ).
   FutureOr<Response<BodyType>> convertResponse<BodyType, InnerType>(
     Response response,
   );
@@ -94,7 +94,7 @@ abstract class Converter {
 /// An interface for implementing error response converters.
 ///
 /// An `ErrorConverter` is called only on error responses
-/// \(statusCode &lt; 200 || statusCode &gt;= 300\) and before any [ResponseInterceptor]s.
+/// (statusCode < 200 || statusCode >= 300) and before any [ResponseInterceptor]s.
 abstract class ErrorConverter {
 
   /// Converts the received [Response] to a [Response] which has a body with the

chopper/pubspec.yaml

@@ -1,7 +1,7 @@
 name: chopper
-description: Chopper is an http client generator using source_gen and inspired from retrofit
+description: Chopper is an http client generator using source_gen, inspired by Retrofit
 version: 3.0.6
-homepage: https://hadrien-lejard.gitbook.io/chopper
+documentation: https://hadrien-lejard.gitbook.io/chopper
 repository: https://github.com/lejard-h/chopper
 author: Hadrien Lejard <[email protected]>
 

chopper_built_value/README.md

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

chopper_built_value/lib/chopper_built_value.dart

@@ -3,11 +3,19 @@ import 'package:chopper/chopper.dart';
 import 'package:built_collection/built_collection.dart';
 import 'package:built_value/serializer.dart';
 
+/// A custom [Converter] and [ErrorConverter] that handles conversion for classes
+/// having a serializer implementation made with the built_value package.
 class BuiltValueConverter implements Converter, ErrorConverter {
   final Serializers serializers;
   final JsonConverter jsonConverter = JsonConverter();
   final Type errorType;
 
+  /// Builds a new BuiltValueConverter instance that uses built_value serializers defined
+  /// in the provided [serializers] parameter.
+  ///
+  /// If the error body cannot be converted with serializers and [errorType] is provided
+  /// and it's not `null`, BuiltValueConverter will try to deserialize the error body into
+  /// [errorType].
   BuiltValueConverter(this.serializers, {this.errorType});
 
   T _deserialize<T>(dynamic value) {

chopper_built_value/pubspec.yaml

@@ -1,7 +1,7 @@
 name: chopper_built_value
-description: Chopper is an http client generator using source_gen and inspired from retrofit
+description: A built_value based Converter for Chopper.
 version: 0.0.6
-homepage: https://hadrien-lejard.gitbook.io/chopper
+documentation: https://hadrien-lejard.gitbook.io/chopper/converters/built-value-converter
 repository: https://github.com/lejard-h/chopper
 author: Hadrien Lejard <[email protected]>
 

chopper_generator/README.md

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

chopper_generator/pubspec.yaml

@@ -1,7 +1,7 @@
 name: chopper_generator
-description: Chopper is an http client generator using source_gen and inspired from retrofit
+description: Chopper is an http client generator using source_gen, inspired by Retrofit
 version: 3.0.6
-homepage: https://hadrien-lejard.gitbook.io/chopper
+documentation: https://hadrien-lejard.gitbook.io/chopper
 repository: https://github.com/lejard-h/chopper
 author: Hadrien Lejard <[email protected]>
 

converters/built-value-converter.md

@@ -1,25 +1,29 @@
-# Built Value Converter
+# BuiltValueConverter
 
 {% hint style="warning" %}
 Experimental
 {% endhint %}
 
-Chopper converter for [built\_value](https://pub.dev/packages/built_value) serializer.
+A Chopper Converter for [built\_value](https://pub.dev/packages/built_value) based serialization.
 
 ## Installation
 
+Add the chopper_built_value package to your project's dependencies in pubspec.yaml:
+
 ```yaml
 # pubspec.yaml
 
 dependencies:
-  chopper_build_value: ^0.0.1
+  chopper_built_value: ^<latest version>
 ```
 
+The latest version is [![pub package](https://img.shields.io/pub/v/chopper_built_value.svg)](https://pub.dartlang.org/packages/chopper_built_value).
+
 ## Getting started
 
 ### Built value
 
-Define your models.
+Define your models as you usually do with built_value.
 
 ```dart
 abstract class DataModel implements Built<DataModel, DataModelBuilder> {
@@ -32,7 +36,7 @@ abstract class DataModel implements Built<DataModel, DataModelBuilder> {
 }
 ```
 
-Aggregate all serializers
+Aggregate all serializers into a top level collection.
 
 ```dart
 /// Collection of generated serializers for the built_value
@@ -42,11 +46,13 @@ Aggregate all serializers
 final Serializers serializers = _$serializers;
 ```
 
-See built\_value [documentation](https://pub.dev/packages/built_value) for more informations.
+See [built\_value documentation](https://pub.dev/packages/built_value) for more information on how built_value works.
 
-### Chopper
+### Using BuiltValueConverter with Chopper
 
-Provide serializers to the converter and to the ChopperClient.
+Build a `BuiltValueConverter` by providing the `built_value` serializer collection.
+
+To use the created converter, pass it to `ChopperClient`'s `converter` constructor parameter. 
 
 ```dart
 final builder = serializers.toBuilder();
@@ -60,12 +66,14 @@ final client = ChopperClient(converter: converter);
 
 #### Error converter
 
-You can use `BuiltValueConverter` as an error converter. It will try to decode error using the `wireName` inside JSON `{"$":"ErrorModel"}` if available.
+`BuiltValueConverter` is also an error converter. It will try to decode error response bodies using the `wireName` inside JSON `{"$":"ErrorModel"}`, if available.
 
-If `wireName` is not available, you can specify the type of your error to the converter.
+If `wireName` is not available, `BuiltValueConverter` will try to convert error response bodies to `errorType`, if it was provided and is not `null`.
 
 ```dart
-BuiltValueConverter(jsonSerializers, errorType: ErrorModel);
+final jsonSerializers = ...
+
+final converter = BuiltValueConverter(jsonSerializers, errorType: ErrorModel);
 ```
 
 

converters/converters.md

@@ -12,7 +12,7 @@ final chopper = ChopperClient(
 ```
 
 {% hint style="info" %}
-The `errorConverter` is called only on error responses \(statusCode < 200 \|\| statusCode >= 300\).
+The `errorConverter` is called only on error responses (statusCode < 200 || statusCode >= 300).
 {% endhint %}
 
 ## The built-in JSON converter
@@ -33,14 +33,14 @@ You can implement custom converters by implementing the `Converter` class.
 class MyConverter implements Converter {
   @override
   Response<BodyType> convertResponse<BodyType, InnerType>(Response response) {
-    var body = response.body
+    var body = response.body;
     // Convert body to BodyType however you like
     response.copyWith<BodyType>(body: body);
   }
 
   @override
   Request convertRequest(Request request) {
-    var body = request.body
+    var body = request.body;
     // Convert body to String however you like    
     return request.copyWith(body: body);
   }

example/pubspec.yaml

@@ -1,7 +1,7 @@
 name: chopper_example
-description: Example of Chopper
+description: Example usage of the Chopper package
 version: 0.0.1
-#homepage: https://www.example.com
+documentation: https://hadrien-lejard.gitbook.io/chopper/
 author: Hadrien Lejard <[email protected]>
 
 environment: