Documentation cleanup (#23)

Author: f3ath

test/Document/CompoundDocumentTest.php

@@ -40,7 +40,7 @@
  * Note: Full linkage ensures that included resources are related to either the primary data
  * (which could be resource objects or resource identifier objects) or to each other.
  *
- * @link http://jsonapi.org/format/#document-compound-documents
+ * @see http://jsonapi.org/format/#document-compound-documents
  */
 class CompoundDocumentTest extends TestCase
 {

test/Document/Resource/Relationship/LinkageTest.php

@@ -18,9 +18,26 @@
 use JsonApiPhp\JsonApi\Document\Resource\Relationship\Linkage;
 use JsonApiPhp\JsonApi\Document\Resource\ResourceId;
 use JsonApiPhp\JsonApi\Test\HasAssertEqualsAsJson;
-use phpDocumentor\Reflection\DocBlock\Tags\Link;
 use PHPUnit\Framework\TestCase;
 
+/**
+ * Resource Linkage
+ *
+ * Resource linkage in a compound document allows a client to link together
+ * all of the included resource objects without having to GET any URLs via links.
+ *
+ * Resource linkage MUST be represented as one of the following:
+ * - null for empty to-one relationships.
+ * - an empty array ([]) for empty to-many relationships.
+ * - a single resource identifier object for non-empty to-one relationships.
+ * - an array of resource identifier objects for non-empty to-many relationships.
+ *
+ * @see http://jsonapi.org/format/#document-resource-object-linkage
+ * @see LinkageTest::testCanCreateNullLinkage()
+ * @see LinkageTest::testCanCreateEmptyArrayLinkage()
+ * @see LinkageTest::testCanCreateFromSingleResourceId()
+ * @see LinkageTest::testCanCreateFromArrayOfResourceIds()
+ */
 class LinkageTest extends TestCase
 {
     use HasAssertEqualsAsJson;
@@ -41,7 +58,7 @@ public function testCanCreateEmptyArrayLinkage()
         );
     }
 
-    public function testCanCreateFromResourceId()
+    public function testCanCreateFromSingleResourceId()
     {
         $this->assertEqualsAsJson(
             [
@@ -52,7 +69,7 @@ public function testCanCreateFromResourceId()
         );
     }
 
-    public function testCanCreateFromResourceIds()
+    public function testCanCreateFromArrayOfResourceIds()
     {
         $this->assertEqualsAsJson(
             [

test/Document/Resource/Relationship/RelationshipTest.php

@@ -19,22 +19,40 @@
 use JsonApiPhp\JsonApi\Test\HasAssertEqualsAsJson;
 use PHPUnit\Framework\TestCase;
 
+/**
+ * Relationships
+ *
+ * The value of the relationships key MUST be an object (a “relationships object”).
+ * Members of the relationships object (“relationships”) represent references
+ * from the resource object in which it’s defined to other resource objects.
+ *
+ * Relationships may be to-one or to-many.
+ *
+ * A “relationship object” MUST contain at least one of the following:
+ *
+ * - links: a links object containing at least one of the following:
+ *      -   self: a link for the relationship itself (a “relationship link”).
+ *          This link allows the client to directly manipulate the relationship.
+ *          For example, removing an author through an article’s relationship URL would disconnect the person
+ *          from the article without deleting the people resource itself. When fetched successfully, this link
+ *          returns the linkage for the related resources as its primary data. (See Fetching Relationships.)
+ *      -   related: a related resource link
+ * - data: resource linkage
+ * - meta: a meta object that contains non-standard meta-information about the relationship.
+ *
+ * A relationship object that represents a to-many relationship MAY also contain
+ * pagination links under the links member, as described below.
+ *
+ * @see http://jsonapi.org/format/#document-resource-object-relationships
+ * @see RelationshipTest::testCanCreateFromSelfLink()
+ * @see RelationshipTest::testCanCreateFromRelatedLink())
+ * @see RelationshipTest::testCanCreateFromLinkage())
+ * @see RelationshipTest::testCanCreateFromMeta())
+ */
 class RelationshipTest extends TestCase
 {
     use HasAssertEqualsAsJson;
 
-    public function testCanCreateFromMeta()
-    {
-        $this->assertEqualsAsJson(
-            [
-                'meta' => [
-                    'a' => 'b',
-                ]
-            ],
-            Relationship::fromMeta(['a' => 'b'])
-        );
-    }
-
     public function testCanCreateFromSelfLink()
     {
         $this->assertEqualsAsJson(
@@ -68,4 +86,16 @@ public function testCanCreateFromLinkage()
             Relationship::fromLinkage(Linkage::nullLinkage())
         );
     }
+
+    public function testCanCreateFromMeta()
+    {
+        $this->assertEqualsAsJson(
+            [
+                'meta' => [
+                    'a' => 'b',
+                ]
+            ],
+            Relationship::fromMeta(['a' => 'b'])
+        );
+    }
 }

test/Document/Resource/ResourceFireldsTest.php

@@ -0,0 +1,55 @@
+<?php
+/**
+ *
+ *  * This file is part of JSON:API implementation for PHP.
+ *  *
+ *  * (c) Alexey Karapetov <karapetov@gmail.com>
+ *  *
+ *  * For the full copyright and license information, please view the LICENSE
+ *  * file that was distributed with this source code.
+ *
+ */
+
+declare(strict_types=1);
+
+namespace JsonApiPhp\JsonApi\Test\Document\Resource;
+
+use JsonApiPhp\JsonApi\Document\Resource\Relationship\Relationship;
+use JsonApiPhp\JsonApi\Document\Resource\ResourceObject;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Fields
+ *
+ * A resource object’s attributes and its relationships are collectively called its “fields”.
+ *
+ * Fields for a resource object MUST share a common namespace with each other and with type and id.
+ * In other words, a resource can not have an attribute and relationship with the same name,
+ * nor can it have an attribute or relationship named type or id.
+ *
+ * @see http://jsonapi.org/format/#document-resource-object-fields
+ */
+class ResourceFieldsTest extends TestCase
+{
+    /**
+     * @expectedException \LogicException
+     * @expectedExceptionMessage Field foo already exists in attributes
+     */
+    public function testCanNotSetRelationshipIfAttributeExists()
+    {
+        $res = new ResourceObject('books', '1');
+        $res->setAttribute('foo', 'bar');
+        $res->setRelationship('foo', Relationship::fromMeta(['a' => 'b']));
+    }
+
+    /**
+     * @expectedException \LogicException
+     * @expectedExceptionMessage Field foo already exists in relationships
+     */
+    public function testCanNotSetAttributeIfRelationshipExists()
+    {
+        $res = new ResourceObject('books', '1');
+        $res->setRelationship('foo', Relationship::fromMeta(['a' => 'b']));
+        $res->setAttribute('foo', 'bar');
+    }
+}

test/Document/Resource/ResourceTest.php

@@ -20,6 +20,11 @@
 use JsonApiPhp\JsonApi\Test\HasAssertEqualsAsJson;
 use PHPUnit\Framework\TestCase;
 
+/**
+ * Resource Objects
+ *
+ * @see http://jsonapi.org/format/#document-resource-objects
+ */
 class ResourceTest extends TestCase
 {
     use HasAssertEqualsAsJson;
@@ -112,26 +117,4 @@ public function invalidAttributeNames(): array
             ['type'],
         ];
     }
-
-    /**
-     * @expectedException \LogicException
-     * @expectedExceptionMessage Field foo already exists in attributes
-     */
-    public function testCanNotSetRelationshipIfAttributeExists()
-    {
-        $res = new ResourceObject('books', '1');
-        $res->setAttribute('foo', 'bar');
-        $res->setRelationship('foo', Relationship::fromMeta(['a' => 'b']));
-    }
-
-    /**
-     * @expectedException \LogicException
-     * @expectedExceptionMessage Field foo already exists in relationships
-     */
-    public function testCanNotSetAttributeIfRelationshipExists()
-    {
-        $res = new ResourceObject('books', '1');
-        $res->setRelationship('foo', Relationship::fromMeta(['a' => 'b']));
-        $res->setAttribute('foo', 'bar');
-    }
 }