From 2570c24390523c4d7ae45a0197dc47e2171c9e44 Mon Sep 17 00:00:00 2001
From: Toby Zerner <toby.zerner@gmail.com>
Date: Sat, 9 May 2020 17:55:09 +0930
Subject: [PATCH] Allow adding inline documentation

---
 src/Handler/Index.php |  2 +-
 src/Schema/Field.php  | 11 +++++++++++
 src/Schema/Filter.php | 43 +++++++++++++++++++++++++++++++++++++++++++
 src/Schema/Type.php   | 13 +++++++++++--
 4 files changed, 66 insertions(+), 3 deletions(-)
 create mode 100644 src/Schema/Filter.php

diff --git a/src/Handler/Index.php b/src/Handler/Index.php
index e9be6d4..b0302db 100644
--- a/src/Handler/Index.php
+++ b/src/Handler/Index.php
@@ -246,7 +246,7 @@ class Index implements RequestHandlerInterface
             }
 
             if (isset($filters[$name])) {
-                $filters[$name]($query, $value, $request);
+                $filters[$name]->getCallback()($query, $value, $request);
                 continue;
             }
 
diff --git a/src/Schema/Field.php b/src/Schema/Field.php
index 5fdf4b1..128d521 100644
--- a/src/Schema/Field.php
+++ b/src/Schema/Field.php
@@ -20,6 +20,7 @@ abstract class Field
     use HasListeners;
 
     private $name;
+    private $description;
     private $property;
     private $visible = true;
     private $single = false;
@@ -41,6 +42,16 @@ abstract class Field
      */
     abstract public function getLocation(): string;
 
+    /**
+     * Set the description of the field for documentation generation.
+     */
+    public function description(string $description)
+    {
+        $this->description = $description;
+
+        return $this;
+    }
+
     /**
      * Set the model property to which this field corresponds.
      */
diff --git a/src/Schema/Filter.php b/src/Schema/Filter.php
new file mode 100644
index 0000000..3fb9a73
--- /dev/null
+++ b/src/Schema/Filter.php
@@ -0,0 +1,43 @@
+<?php
+
+/*
+ * This file is part of tobyz/json-api-server.
+ *
+ * (c) Toby Zerner <toby.zerner@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Tobyz\JsonApiServer\Schema;
+
+final class Filter
+{
+    private $name;
+    private $callback;
+    private $description;
+
+    public function __construct(string $name, callable $callback)
+    {
+        $this->name = $name;
+        $this->callback = $callback;
+    }
+
+    public function getName(): string
+    {
+        return $this->name;
+    }
+
+    public function getCallback(): callable
+    {
+        return $this->callback;
+    }
+
+    /**
+     * Set the description of the type for documentation generation.
+     */
+    public function description(string $description)
+    {
+        $this->description = $description;
+    }
+}
diff --git a/src/Schema/Type.php b/src/Schema/Type.php
index 9bf674c..78d50fd 100644
--- a/src/Schema/Type.php
+++ b/src/Schema/Type.php
@@ -19,6 +19,7 @@ final class Type
 {
     use HasListeners, HasMeta;
 
+    private $description;
     private $fields = [];
     private $filters = [];
     private $sortFields = [];
@@ -35,6 +36,14 @@ final class Type
     private $deletable = false;
     private $deleteCallback;
 
+    /**
+     * Set the description of the type for documentation generation.
+     */
+    public function description(string $description)
+    {
+        $this->description = $description;
+    }
+
     /**
      * Add an attribute to the resource type.
      *
@@ -98,9 +107,9 @@ final class Type
     /**
      * Add a filter to the resource type.
      */
-    public function filter(string $name, callable $callback): void
+    public function filter(string $name, callable $callback): Filter
     {
-        $this->filters[$name] = $callback;
+        return $this->filters[$name] = new Filter($name, $callback);
     }
 
     /**