Merge pull request #61 from clue/docs-file-names

Improve documentation to use titles for file names instead of comments

docs/api/app.md

@@ -3,8 +3,7 @@
 The `App` class is your main entrypoint to any application that builds on top of X.
 It provides a simple API for routing HTTP requests as commonly used in RESTful applications.
 
-```php
-# public/index.php
+```php title="public/index.php"
 <?php
 
 require __DIR__ . '/../vendor/autoload.php';
@@ -112,13 +111,11 @@ you keep adding more controllers to a single application.
 For this reason, we recommend using [controller classes](../best-practices/controllers.md)
 for production use-cases like this:
 
-```php
-# public/index.php
+```php title="public/index.php"
 $app->get('/', new Acme\Todo\HelloController());
 ```
 
-```php
-# src/HelloController.php
+```php title="src/HelloController.php"
 <?php
 
 namespace Acme\Todo;

docs/api/middleware.md

@@ -52,8 +52,7 @@ keep adding more controllers to a single application.
 For this reason, we recommend using middleware classes for production use-cases
 like this:
 
-```php
-# src/DemoMiddleware.php
+```php title="src/DemoMiddleware.php"
 <?php
 
 namespace Acme\Todo;
@@ -82,8 +81,7 @@ class DemoMiddleware
     }
 }
 ```
-```php
-# public/index.php
+```php title="public/index.php"
 <?php
 
 use Acme\Todo\DemoMiddleware;
@@ -108,8 +106,7 @@ Accordingly, all examples below use middleware classes as the recommended style.
 
 To get started, we can add an example middleware handler that can modify the incoming request:
 
-```php
-# src/AdminMiddleware.php
+```php title="src/AdminMiddleware.php"
 <?php
 
 namespace Acme\Todo;
@@ -130,8 +127,7 @@ class AdminMiddleware
 }
 ```
 
-```php
-# src/UserController.php
+```php title="src/UserController.php"
 <?php
 
 namespace Acme\Todo;
@@ -176,8 +172,7 @@ object, see also the next chapter.
 
 Likewise, we can add an example middleware handler that can modify the outgoing response:
 
-```php
-# src/ContentTypeMiddleware.php
+```php title="src/ContentTypeMiddleware.php"
 <?php
 
 namespace Acme\Todo;
@@ -197,8 +192,7 @@ class ContentTypeMiddleware
 }
 ```
 
-```php
-# src/UserController.php
+```php title="src/UserController.php"
 <?php
 
 namespace Acme\Todo;
@@ -216,8 +210,7 @@ class UserController
 }
 ```
 
-```php
-# public/index.php
+```php title="public/index.php"
 <?php
 
 use Acme\Todo\ContentTypeMiddleware;
@@ -254,8 +247,7 @@ a response object synchronously:
 
 === "Arrow functions (PHP 7.4+)"
 
-    ```php
-    # src/AsyncAwareContentTypeMiddleware.php
+    ```php title="src/AsyncAwareContentTypeMiddleware.php"
     <?php
 
     namespace Acme\Todo;
@@ -288,8 +280,7 @@ a response object synchronously:
 
 === "Match syntax (PHP 8.0+)"
 
-    ```php
-    # src/AsyncAwareContentTypeMiddleware.php
+    ```php title="src/AsyncAwareContentTypeMiddleware.php"
     <?php
 
     namespace Acme\Todo;
@@ -320,8 +311,7 @@ a response object synchronously:
 
 === "Closures"
 
-    ```php
-    # src/AsyncAwareContentTypeMiddleware.php
+    ```php title="src/AsyncAwareContentTypeMiddleware.php"
     <?php
 
     namespace Acme\Todo;
@@ -360,8 +350,7 @@ a response object synchronously:
 
 === "Coroutines"
 
-    ```php
-    # src/AsyncUserController.php
+    ```php title="src/AsyncUserController.php"
     <?php
 
     namespace Acme\Todo;
@@ -401,8 +390,7 @@ a response object synchronously:
 
 === "Promises"
 
-    ```php
-    # src/AsyncUserController.php
+    ```php title="src/AsyncUserController.php"
     <?php
 
     namespace Acme\Todo;
@@ -441,8 +429,7 @@ a response object synchronously:
     ```
 
 
-```php
-# public/index.php
+```php title="public/index.php"
 <?php
 
 use Acme\Todo\AsyncContentTypeMiddleware;
@@ -469,8 +456,7 @@ This is commonly used for cache handling and response body transformations (comp
 Additionally, you can also add middleware to the [`App`](app.md) object itself
 to register a global middleware handler:
 
-```php hl_lines="7"
-# public/index.php
+```php hl_lines="7" title="public/index.php"
 <?php
 
 use Acme\Todo\AdminMiddleware;

docs/best-practices/controllers.md

@@ -7,8 +7,7 @@ This is especially useful once you leave the prototyping phase and want to find
 
 To get started, let's take a look at the following simple closure definitions:
 
-```php
-# public/index.php
+```php title="public/index.php"
 <?php
 
 require __DIR__ . '/../vendor/autoload.php';
@@ -41,8 +40,7 @@ For real-world applications, we highly recommend structuring your application
 into invidividual controller classes. This way, we can break up the above
 definition into three even simpler files:
 
-```php
-# public/index.php
+```php title="public/index.php"
 <?php
 
 require __DIR__ . '/../vendor/autoload.php';
@@ -55,8 +53,7 @@ $app->get('/users/{name}', new Acme\Todo\UserController());
 $app->run();
 ```
 
-```php
-# src/HelloController.php
+```php title="src/HelloController.php"
 <?php
 
 namespace Acme\Todo;
@@ -76,8 +73,7 @@ class HelloController
 }
 ```
 
-```php
-# src/UserController.php
+```php title="src/UserController.php"
 <?php
 
 namespace Acme\Todo;
@@ -102,7 +98,7 @@ Doesn't look too complex, right? Now, we only need to tell Composer's autoloader
 about our vendor namespace `Acme\Todo` in the `src/` folder. Make sure to include
 the following lines in your `composer.json` file:
 
-```json
+```json title="composer.json"
 {
     "autoload": {
         "psr-4": {

docs/best-practices/deployment.md

@@ -120,8 +120,7 @@ to instruct Apache to rewrite dynamic requests so they will be processed by X.
 Inside your `public/` directory, create an `.htaccess` file (note the leading `.` which
 makes this a hidden file) with the following contents:
 
-```
-# public/.htaccess
+``` title="public/.htaccess"
 RewriteEngine On
 
 RewriteCond %{REQUEST_FILENAME} !-d
@@ -243,7 +242,7 @@ directory like this:
 $ sudoedit /etc/systemd/system/acme.service
 ```
 
-```
+``` title="/etc/systemd/system/acme.service"
 [Unit]
 Description=ACME server
 

docs/best-practices/testing.md

@@ -22,8 +22,7 @@ This way, testing becomes pretty straight forward.
 
 Let's start simple and write some unit tests for our simple `HelloController` class:
 
-```php
-# src/HelloController.php
+```php title="src/HelloController.php"
 <?php
 
 namespace Acme\Todo;
@@ -59,8 +58,7 @@ $ composer require --dev phpunit/phpunit
 
 Next, we can start by creating our first unit test:
 
-```php
-# tests/HelloControllerTest.php
+```php title="tests/HelloControllerTest.php"
 <?php
 
 namespace Acme\Tests\Todo;
@@ -117,8 +115,7 @@ shows different behavior depending on what HTTP request comes in.
 For this example, we're using [request attributes](../api/request.md#attributes),
 but the same logic applies to testing different URLs, HTTP request headers, etc.:
 
-```php
-# src/UserController.php
+```php title="src/UserController.php"
 <?php
 
 namespace Acme\Todo;
@@ -141,8 +138,7 @@ class UserController
 
 Again, we create a new test class matching the controller class:
 
-```php
-# tests/UserControllerTest.php
+```php title="tests/UserControllerTest.php"
 <?php
 
 namespace Acme\Tests\Todo;

docs/getting-started/quickstart.md

@@ -18,7 +18,7 @@ Next, we can start by taking a look at a simple example application.
 You can use this example to get started by creating a new `public/` directory with
 an `index.php` file inside:
 
-```php
+```php title="public/index.php"
 <?php
 
 require __DIR__ . '/../vendor/autoload.php';
@@ -59,7 +59,7 @@ Next, we need to install X and its dependencies to actually run this project.
 >
 > Start by creating a new `composer.json` in the project directory with the following contents:
 > 
-> ```json
+> ```json title="composer.json"
 > {
 >     "repositories": [
 >         {