{"action":"created","comment":{"url":"https://api.github.com/repos/graze/standards/pulls/comments/57910051","id":57910051,"diff_hunk":"@@ -55,27 +42,63 @@ The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL NOT\", \"SHOULD\", \"S\n   }\n   ```\n \n-15. There MUST NOT be any assignment or modification of variables in the expressions of `if` statements.\n+13. There MUST NOT be any assignment or modification of variables in the expressions of `if` statements.\n \n   ```php\n   if ($response = $request->getResponse()) {\n     // not allowed\n   }\n   ```\n-16. Abstract class names MUST begin with `Abstract`.\n+14. Abstract class names MUST begin with `Abstract`.\n \n   ```php\n   abstract class AbstractGenerator {\n   }\n   ```\n-17. Interface names MUST end with `Interface`.\n+15. Interface names MUST end with `Interface`.\n \n   ```php\n   interface GeneratorInterface {\n   }\n   ```\n \n-18. Doc block types for scalar values MUST be one of: `bool` (not boolean), `int` (not integer), `string`, `float` (not double)\n+### PHP DocBlock\n+1. DocBlock for functions / methods MUST exist where the function / method has arguments or a return value and MUST use the appropriate tags (@param, @return) to denote that. Developers making modifications to a function / method are tasked with ensuring that the DocBlock is up-to-date.\n+2. Functions / methods / classes that are sufficiently complex (i.e. not self-documenting) SHOULD have a DocBlock explaining how to use the function / method / class.\n+3. DocBlock presenting the type MUST be present for class member variables.\n+4. When a description is necessary for class member variables, the DocBlock MUST be multiline:\n+\n+  ```php\n+  class Foo\n+  {\n+      /** @var int */\n+      protected $id;\n+      \n+      /**\n+       * The Bar used to fight the foo\n+       * @var Bar\n+       */\n+      private $bar;\n+  }\n+  ```\n+\n+5. DocBlock types for scalar values MUST be one of: `bool` (not boolean), `int` (not integer), `string`, `float` (not double).\n+6. DocBlock types for parameters/return values that are arrays of a single type MUST be written as: `Type[]`. If the variable is a multi-dimensional array, it MUST be represented with one set of `[]` per depth (`int[][]` for an array of array of ints)\n+7. If the parameter/return value is an array of several types, it MUST be described in the DocBlock as `mixed[]`.\n+8. If the parameter/return value is an array that is sometimes empty, it MUST still be written as in 6) (NOT `Type[]|[]`)\n+\n+**example of a method's DocBlock:**\n+```\n+    /**\n+     * Foos the bars.\n+     *\n+     * @param int $barId Some number\n+     * @param Bar[] $allTheBars Collection of Bar objects\n+     * @return string[] List of messages","path":"README.md","position":87,"original_position":88,"commit_id":"3ba5ff59c304ef1a1f4cf4ad64687626e7aff131","original_commit_id":"3b5a334a23dc8cf6c63bfeda5d7f61c655388908","user":{"login":"wpillar","id":188514,"avatar_url":"https://avatars.githubusercontent.com/u/188514?v=3","gravatar_id":"","url":"https://api.github.com/users/wpillar","html_url":"https://github.com/wpillar","followers_url":"https://api.github.com/users/wpillar/followers","following_url":"https://api.github.com/users/wpillar/following{/other_user}","gists_url":"https://api.github.com/users/wpillar/gists{/gist_id}","starred_url":"https://api.github.com/users/wpillar/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/wpillar/subscriptions","organizations_url":"https://api.github.com/users/wpillar/orgs","repos_url":"https://api.github.com/users/wpillar/repos","events_url":"https://api.github.com/users/wpillar/events{/privacy}","received_events_url":"https://api.github.com/users/wpillar/received_events","type":"User","site_admin":false},"body":">9. It is RECOMMENDED there be a blank line between `@param` and `@return` tags, though this is not required.\r\n\r\n?","created_at":"2016-03-30T15:36:00Z","updated_at":"2016-03-30T15:36:00Z","html_url":"https://github.com/graze/standards/pull/25#discussion_r57910051","pull_request_url":"https://api.github.com/repos/graze/standards/pulls/25","_links":{"self":{"href":"https://api.github.com/repos/graze/standards/pulls/comments/57910051"},"html":{"href":"https://github.com/graze/standards/pull/25#discussion_r57910051"},"pull_request":{"href":"https://api.github.com/repos/graze/standards/pulls/25"}}},"pull_request":{"url":"https://api.github.com/repos/graze/standards/pulls/25","id":64647011,"html_url":"https://github.com/graze/standards/pull/25","diff_url":"https://github.com/graze/standards/pull/25.diff","patch_url":"https://github.com/graze/standards/pull/25.patch","issue_url":"https://api.github.com/repos/graze/standards/issues/25","number":25,"state":"open","locked":false,"title":"Docblock standards","user":{"login":"mathieupinet","id":637791,"avatar_url":"https://avatars.githubusercontent.com/u/637791?v=3","gravatar_id":"","url":"https://api.github.com/users/mathieupinet","html_url":"https://github.com/mathieupinet","followers_url":"https://api.github.com/users/mathieupinet/followers","following_url":"https://api.github.com/users/mathieupinet/following{/other_user}","gists_url":"https://api.github.com/users/mathieupinet/gists{/gist_id}","starred_url":"https://api.github.com/users/mathieupinet/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mathieupinet/subscriptions","organizations_url":"https://api.github.com/users/mathieupinet/orgs","repos_url":"https://api.github.com/users/mathieupinet/repos","events_url":"https://api.github.com/users/mathieupinet/events{/privacy}","received_events_url":"https://api.github.com/users/mathieupinet/received_events","type":"User","site_admin":false},"body":"New standards:\r\n\r\n* single-line & multi-line class variable blocks\r\n* array of things","created_at":"2016-03-30T15:27:54Z","updated_at":"2016-03-30T15:36:00Z","closed_at":null,"merged_at":null,"merge_commit_sha":"fb26e69a9ac1c645d98c6168e41eff8e55cd52b8","assignee":{"login":"wpillar","id":188514,"avatar_url":"https://avatars.githubusercontent.com/u/188514?v=3","gravatar_id":"","url":"https://api.github.com/users/wpillar","html_url":"https://github.com/wpillar","followers_url":"https://api.github.com/users/wpillar/followers","following_url":"https://api.github.com/users/wpillar/following{/other_user}","gists_url":"https://api.github.com/users/wpillar/gists{/gist_id}","starred_url":"https://api.github.com/users/wpillar/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/wpillar/subscriptions","organizations_url":"https://api.github.com/users/wpillar/orgs","repos_url":"https://api.github.com/users/wpillar/repos","events_url":"https://api.github.com/users/wpillar/events{/privacy}","received_events_url":"https://api.github.com/users/wpillar/received_events","type":"User","site_admin":false},"milestone":null,"commits_url":"https://api.github.com/repos/graze/standards/pulls/25/commits","review_comments_url":"https://api.github.com/repos/graze/standards/pulls/25/comments","review_comment_url":"https://api.github.com/repos/graze/standards/pulls/comments{/number}","comments_url":"https://api.github.com/repos/graze/standards/issues/25/comments","statuses_url":"https://api.github.com/repos/graze/standards/statuses/3ba5ff59c304ef1a1f4cf4ad64687626e7aff131","head":{"label":"graze:docblock-standards","ref":"docblock-standards","sha":"3ba5ff59c304ef1a1f4cf4ad64687626e7aff131","user":{"login":"graze","id":637788,"avatar_url":"https://avatars.githubusercontent.com/u/637788?v=3","gravatar_id":"","url":"https://api.github.com/users/graze","html_url":"https://github.com/graze","followers_url":"https://api.github.com/users/graze/followers","following_url":"https://api.github.com/users/graze/following{/other_user}","gists_url":"https://api.github.com/users/graze/gists{/gist_id}","starred_url":"https://api.github.com/users/graze/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/graze/subscriptions","organizations_url":"https://api.github.com/users/graze/orgs","repos_url":"https://api.github.com/users/graze/repos","events_url":"https://api.github.com/users/graze/events{/privacy}","received_events_url":"https://api.github.com/users/graze/received_events","type":"Organization","site_admin":false},"repo":{"id":21660050,"name":"standards","full_name":"graze/standards","owner":{"login":"graze","id":637788,"avatar_url":"https://avatars.githubusercontent.com/u/637788?v=3","gravatar_id":"","url":"https://api.github.com/users/graze","html_url":"https://github.com/graze","followers_url":"https://api.github.com/users/graze/followers","following_url":"https://api.github.com/users/graze/following{/other_user}","gists_url":"https://api.github.com/users/graze/gists{/gist_id}","starred_url":"https://api.github.com/users/graze/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/graze/subscriptions","organizations_url":"https://api.github.com/users/graze/orgs","repos_url":"https://api.github.com/users/graze/repos","events_url":"https://api.github.com/users/graze/events{/privacy}","received_events_url":"https://api.github.com/users/graze/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/graze/standards","description":"⚖ The coding standards of the graze tech team.","fork":false,"url":"https://api.github.com/repos/graze/standards","forks_url":"https://api.github.com/repos/graze/standards/forks","keys_url":"https://api.github.com/repos/graze/standards/keys{/key_id}","collaborators_url":"https://api.github.com/repos/graze/standards/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/graze/standards/teams","hooks_url":"https://api.github.com/repos/graze/standards/hooks","issue_events_url":"https://api.github.com/repos/graze/standards/issues/events{/number}","events_url":"https://api.github.com/repos/graze/standards/events","assignees_url":"https://api.github.com/repos/graze/standards/assignees{/user}","branches_url":"https://api.github.com/repos/graze/standards/branches{/branch}","tags_url":"https://api.github.com/repos/graze/standards/tags","blobs_url":"https://api.github.com/repos/graze/standards/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/graze/standards/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/graze/standards/git/refs{/sha}","trees_url":"https://api.github.com/repos/graze/standards/git/trees{/sha}","statuses_url":"https://api.github.com/repos/graze/standards/statuses/{sha}","languages_url":"https://api.github.com/repos/graze/standards/languages","stargazers_url":"https://api.github.com/repos/graze/standards/stargazers","contributors_url":"https://api.github.com/repos/graze/standards/contributors","subscribers_url":"https://api.github.com/repos/graze/standards/subscribers","subscription_url":"https://api.github.com/repos/graze/standards/subscription","commits_url":"https://api.github.com/repos/graze/standards/commits{/sha}","git_commits_url":"https://api.github.com/repos/graze/standards/git/commits{/sha}","comments_url":"https://api.github.com/repos/graze/standards/comments{/number}","issue_comment_url":"https://api.github.com/repos/graze/standards/issues/comments{/number}","contents_url":"https://api.github.com/repos/graze/standards/contents/{+path}","compare_url":"https://api.github.com/repos/graze/standards/compare/{base}...{head}","merges_url":"https://api.github.com/repos/graze/standards/merges","archive_url":"https://api.github.com/repos/graze/standards/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/graze/standards/downloads","issues_url":"https://api.github.com/repos/graze/standards/issues{/number}","pulls_url":"https://api.github.com/repos/graze/standards/pulls{/number}","milestones_url":"https://api.github.com/repos/graze/standards/milestones{/number}","notifications_url":"https://api.github.com/repos/graze/standards/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/graze/standards/labels{/name}","releases_url":"https://api.github.com/repos/graze/standards/releases{/id}","deployments_url":"https://api.github.com/repos/graze/standards/deployments","created_at":"2014-07-09T16:31:03Z","updated_at":"2016-02-16T15:31:50Z","pushed_at":"2016-03-30T15:32:49Z","git_url":"git://github.com/graze/standards.git","ssh_url":"git@github.com:graze/standards.git","clone_url":"https://github.com/graze/standards.git","svn_url":"https://github.com/graze/standards","homepage":"","size":53,"stargazers_count":0,"watchers_count":0,"language":"PHP","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":2,"forks":0,"open_issues":2,"watchers":0,"default_branch":"master"}},"base":{"label":"graze:master","ref":"master","sha":"0892b5a4cee97dcd4fd17d6f80af988664c5f870","user":{"login":"graze","id":637788,"avatar_url":"https://avatars.githubusercontent.com/u/637788?v=3","gravatar_id":"","url":"https://api.github.com/users/graze","html_url":"https://github.com/graze","followers_url":"https://api.github.com/users/graze/followers","following_url":"https://api.github.com/users/graze/following{/other_user}","gists_url":"https://api.github.com/users/graze/gists{/gist_id}","starred_url":"https://api.github.com/users/graze/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/graze/subscriptions","organizations_url":"https://api.github.com/users/graze/orgs","repos_url":"https://api.github.com/users/graze/repos","events_url":"https://api.github.com/users/graze/events{/privacy}","received_events_url":"https://api.github.com/users/graze/received_events","type":"Organization","site_admin":false},"repo":{"id":21660050,"name":"standards","full_name":"graze/standards","owner":{"login":"graze","id":637788,"avatar_url":"https://avatars.githubusercontent.com/u/637788?v=3","gravatar_id":"","url":"https://api.github.com/users/graze","html_url":"https://github.com/graze","followers_url":"https://api.github.com/users/graze/followers","following_url":"https://api.github.com/users/graze/following{/other_user}","gists_url":"https://api.github.com/users/graze/gists{/gist_id}","starred_url":"https://api.github.com/users/graze/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/graze/subscriptions","organizations_url":"https://api.github.com/users/graze/orgs","repos_url":"https://api.github.com/users/graze/repos","events_url":"https://api.github.com/users/graze/events{/privacy}","received_events_url":"https://api.github.com/users/graze/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/graze/standards","description":"⚖ The coding standards of the graze tech team.","fork":false,"url":"https://api.github.com/repos/graze/standards","forks_url":"https://api.github.com/repos/graze/standards/forks","keys_url":"https://api.github.com/repos/graze/standards/keys{/key_id}","collaborators_url":"https://api.github.com/repos/graze/standards/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/graze/standards/teams","hooks_url":"https://api.github.com/repos/graze/standards/hooks","issue_events_url":"https://api.github.com/repos/graze/standards/issues/events{/number}","events_url":"https://api.github.com/repos/graze/standards/events","assignees_url":"https://api.github.com/repos/graze/standards/assignees{/user}","branches_url":"https://api.github.com/repos/graze/standards/branches{/branch}","tags_url":"https://api.github.com/repos/graze/standards/tags","blobs_url":"https://api.github.com/repos/graze/standards/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/graze/standards/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/graze/standards/git/refs{/sha}","trees_url":"https://api.github.com/repos/graze/standards/git/trees{/sha}","statuses_url":"https://api.github.com/repos/graze/standards/statuses/{sha}","languages_url":"https://api.github.com/repos/graze/standards/languages","stargazers_url":"https://api.github.com/repos/graze/standards/stargazers","contributors_url":"https://api.github.com/repos/graze/standards/contributors","subscribers_url":"https://api.github.com/repos/graze/standards/subscribers","subscription_url":"https://api.github.com/repos/graze/standards/subscription","commits_url":"https://api.github.com/repos/graze/standards/commits{/sha}","git_commits_url":"https://api.github.com/repos/graze/standards/git/commits{/sha}","comments_url":"https://api.github.com/repos/graze/standards/comments{/number}","issue_comment_url":"https://api.github.com/repos/graze/standards/issues/comments{/number}","contents_url":"https://api.github.com/repos/graze/standards/contents/{+path}","compare_url":"https://api.github.com/repos/graze/standards/compare/{base}...{head}","merges_url":"https://api.github.com/repos/graze/standards/merges","archive_url":"https://api.github.com/repos/graze/standards/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/graze/standards/downloads","issues_url":"https://api.github.com/repos/graze/standards/issues{/number}","pulls_url":"https://api.github.com/repos/graze/standards/pulls{/number}","milestones_url":"https://api.github.com/repos/graze/standards/milestones{/number}","notifications_url":"https://api.github.com/repos/graze/standards/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/graze/standards/labels{/name}","releases_url":"https://api.github.com/repos/graze/standards/releases{/id}","deployments_url":"https://api.github.com/repos/graze/standards/deployments","created_at":"2014-07-09T16:31:03Z","updated_at":"2016-02-16T15:31:50Z","pushed_at":"2016-03-30T15:32:49Z","git_url":"git://github.com/graze/standards.git","ssh_url":"git@github.com:graze/standards.git","clone_url":"https://github.com/graze/standards.git","svn_url":"https://github.com/graze/standards","homepage":"","size":53,"stargazers_count":0,"watchers_count":0,"language":"PHP","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":2,"forks":0,"open_issues":2,"watchers":0,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/graze/standards/pulls/25"},"html":{"href":"https://github.com/graze/standards/pull/25"},"issue":{"href":"https://api.github.com/repos/graze/standards/issues/25"},"comments":{"href":"https://api.github.com/repos/graze/standards/issues/25/comments"},"review_comments":{"href":"https://api.github.com/repos/graze/standards/pulls/25/comments"},"review_comment":{"href":"https://api.github.com/repos/graze/standards/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/graze/standards/pulls/25/commits"},"statuses":{"href":"https://api.github.com/repos/graze/standards/statuses/3ba5ff59c304ef1a1f4cf4ad64687626e7aff131"}}}}