Improve documentation

docs/advanced/http-headers.rst

@@ -55,7 +55,6 @@ Send HTTP Headers on server responses
 
 In your server implementation you can set HTTP headers using ``Twirp\Context::withHttpResponseHeader``.
 
-
 .. code-block:: php
 
     <?php

docs/advanced/other-services.rst

@@ -1,5 +1,5 @@
-Serving TwirPHP with other services
-===================================
+Serving multiple Twirp services together
+========================================
 
 In some cases you might want to serve not just one, but multiple services from one application.
 The generated code contains a simple server implementation which lets you mux different services.
@@ -18,7 +18,7 @@ The generated code contains a simple server implementation which lets you mux di
         )
     );
 
-Both the server and service server implement the same ``RequestHandler`` interface, so you can use the same code
+Both the server and service server implement the same ``Twirp\RequestHandler`` interface, so you can use the same code
 as in the :ref:`run-server` usage example:
 
 .. code-block:: php

docs/getting-started/best-practices.rst

@@ -4,6 +4,7 @@ Best Practices
 This page contains some best practices related to using TwirPHP in general.
 Make sure to check out the `official best practices guide`_ as well for Twirp and protobuf related practices.
 
+
 Folder/Package Structure
 ------------------------
 

docs/getting-started/installation.rst

@@ -25,9 +25,9 @@ TwirPHP protoc plugin
 ---------------------
 
 Just like in case of ``protoc``, the easiest way to install the plugin
-by downloading it from the `Github Releases <https://github.com/twirphp/twirp/releases>`_ page.
+is downloading it from the `Github Releases <https://github.com/twirphp/twirp/releases>`_ page.
 
-Make sure to save the binary exactly it is found in the downloaded archive.
+Make sure to save the binary with the same name as it is found in the downloaded archive.
 Also, make sure you place the binary in your ``$PATH``, otherwise you will have to
 tell ``protoc`` where you saved the plugin:
 
@@ -79,7 +79,7 @@ The PHP package can be installed via `Composer`_:
 Shared PHP library
 ------------------
 
-In order to make the generated code work (in a PHP project) you need to install the shared library
+In order to make the generated code work (in a PHP project) you need to install the (minimal) shared library
 via `Composer`_.
 
 .. code-block:: bash

docs/getting-started/overview.rst

@@ -9,8 +9,10 @@ Similar to Twirp itself, TwirPHP comes with two components:
 The code generator is used to generate the Twirp specific server and client files.
 The generated code tries to be as self-contained as possible,
 keeping the runtime library small.
-This concept is present in Twirp itself as well, see the details of this
-decision in the `introductory post`_.
+This concept is present in Twirp itself as well.
+The reason behind is to prevent accidental backward incompatible changes in the
+shared library break your code.
+See more about this in the `introductory post`_.
 
 The shared library contains common interfaces and some code that is part of the
 protocol itself. It can be installed via `Composer`_.
@@ -25,8 +27,13 @@ on the original library.
 In order to track which version of the `Twirp specification`_ is supported,
 please refer to the `TWIRP_VERSION`_ file in the repository.
 
+Twirp version changes will always trigger a new major version,
+but it might also contain backward incompatible changes of the library itself,
+so keep an eye on the `Change Log`_.
+
 
 .. _introductory post: https://blog.twitch.tv/twirp-a-sweet-new-rpc-framework-for-go-5f2febbf35f#d1bb
 .. _Composer: https://getcomposer.org
 .. _Twirp specification: https://twitchtv.github.io/twirp/docs/spec_v5.html
 .. _TWIRP_VERSION: https://github.com/twirphp/twirp/blob/master/TWIRP_VERSION
+.. _Change Log: https://github.com/twirphp/twirp/blob/master/CHANGELOG.md

docs/getting-started/usage.rst

@@ -4,18 +4,20 @@ Usage Example
 This page contains a full example about using TwirPHP on both server and client side.
 Much of it is based on the `original usage example <https://twitchtv.github.io/twirp/docs/example.html>`_,
 so you might want to check that out as well.
-The complete example is available under the `examples <https://github.com/twirphp/twirp/tree/master/example>`_ directory of the project git repository.
+The complete example is available under the `example <https://github.com/twirphp/twirp/tree/master/example>`_
+directory of the project's git repository.
 
 Before moving forward, make sure to check the :doc:`installation` guide as well.
 
 .. contents::
     :local:
 
+
 Write a Protobuf service definition
 -----------------------------------
 
 Write a protobuf definition for your messages and your service and put it in ``proto/service.proto``.
-The following example is taken from the `original usage example <https://twitchtv.github.io/twirp/docs/example.html#write-a-protobuf-service-definition>`_.
+The following example is taken from the `original Twirp documentation <https://twitchtv.github.io/twirp/docs/example.html#write-a-protobuf-service-definition>`_.
 
 .. code-block:: protobuf
 
@@ -91,7 +93,8 @@ Run the server
 --------------
 
 To run the server you need to setup some sort of application entrypoint that processes incoming requests as `PSR-7`_
-messages. It is recommended that you use some sort of dispatcher, like `Zend Diactoros`_, but the following example
+messages. It is recommended that you use some sort of dispatcher/emitter,
+like the ``SapiEmitter`` bundled with `Zend Diactoros`_, but the following example
 works perfectly as well:
 
 .. code-block:: php
@@ -108,14 +111,23 @@ works perfectly as well:
 
     if (!headers_sent()) {
         // status
-        header(sprintf('HTTP/%s %s %s', $response->getProtocolVersion(), $response->getStatusCode(), $response->getReasonPhrase()), true, $response->getStatusCode());
+        header(sprintf(
+            'HTTP/%s %s %s',
+            $response->getProtocolVersion(),
+            $response->getStatusCode(),
+            $response->getReasonPhrase()),
+            true,
+            $response->getStatusCode()
+        );
+
         // headers
         foreach ($response->getHeaders() as $header => $values) {
             foreach ($values as $value) {
                 header($header.': '.$value, false, $response->getStatusCode());
             }
         }
     }
+
     echo $response->getBody();
 
 
@@ -127,6 +139,8 @@ Client stubs are automatically generated, hooray!
 The original library offers two clients to be generated differing in the underlying serialization: JSON and Protobuf.
 This library only offers Protobuf as per the official recommendation.
 
+.. note:: This may change in the future based on demand.
+
 Using the client is quite trivial, you only need to pass an endpoint to the generated client:
 
 .. code-block:: php
@@ -150,6 +164,8 @@ Using the client is quite trivial, you only need to pass an endpoint to the gene
         ]));
     }
 
+.. warning:: When no scheme is present in the endpoint, the client falls back to `HTTP`.
+
 
 .. _PSR-7: http://www.php-fig.org/psr/psr-7/
 .. _Zend Diactoros: https://zendframework.github.io/zend-diactoros/usage/#server-side-applications

docs/index.rst

@@ -6,7 +6,7 @@ Unfortunately (or not?) it only supports Go and Python officially.
 While in the modern world it may be enough for most of the projects,
 there is still a considerable number of PHP-based softwares out there.
 
-This project is a PHP port of Twirp supporting both server and client side.
+TwirPHP is a PHP port of Twirp supporting both server and client side.
 It generates code the same way as Twirp does and follows the same conventions.
 Because of that this documentation only contains minimal information about how
 Twirp works internally. To learn more about it, you should check the following