{"action":"created","issue":{"url":"https://api.github.com/repos/sonata-project/dev-kit/issues/18","repository_url":"https://api.github.com/repos/sonata-project/dev-kit","labels_url":"https://api.github.com/repos/sonata-project/dev-kit/issues/18/labels{/name}","comments_url":"https://api.github.com/repos/sonata-project/dev-kit/issues/18/comments","events_url":"https://api.github.com/repos/sonata-project/dev-kit/issues/18/events","html_url":"https://github.com/sonata-project/dev-kit/issues/18","id":150557117,"number":18,"title":"codestyle: enforce phpdoc textual description","user":{"login":"ju1ius","id":218404,"avatar_url":"https://avatars.githubusercontent.com/u/218404?v=3","gravatar_id":"","url":"https://api.github.com/users/ju1ius","html_url":"https://github.com/ju1ius","followers_url":"https://api.github.com/users/ju1ius/followers","following_url":"https://api.github.com/users/ju1ius/following{/other_user}","gists_url":"https://api.github.com/users/ju1ius/gists{/gist_id}","starred_url":"https://api.github.com/users/ju1ius/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ju1ius/subscriptions","organizations_url":"https://api.github.com/users/ju1ius/orgs","repos_url":"https://api.github.com/users/ju1ius/repos","events_url":"https://api.github.com/users/ju1ius/events{/privacy}","received_events_url":"https://api.github.com/users/ju1ius/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":6,"created_at":"2016-04-23T13:57:06Z","updated_at":"2016-04-23T14:28:03Z","closed_at":null,"body":"A lot of the code right now use IDE oriented php docblocks, giving only the params & return types but no human-friendly description.\r\nWhile this is useful for autocompletion, it is frustrating when you try to fix something,  add a feature, extend a class, implement an interface, etc... Because what the method does is not described, you have to read it's code (and sometimes read through a dozen others), just to know if this is the one you should use/implement or not.\r\n\r\nSo I propose enforcing that:\r\n* all methods have a docblock with `@param`, `@returns` (and `@throws` when needed) \r\n* all public/protected methods MUST have a textual description. \r\n* private methods MUST have a textual description, unless they are very short (one loc or one loc + a return statement). \r\n\r\nAs with the commit messages, give some examples of what's a good description and what's not."},"comment":{"url":"https://api.github.com/repos/sonata-project/dev-kit/issues/comments/213750280","html_url":"https://github.com/sonata-project/dev-kit/issues/18#issuecomment-213750280","issue_url":"https://api.github.com/repos/sonata-project/dev-kit/issues/18","id":213750280,"user":{"login":"greg0ire","id":657779,"avatar_url":"https://avatars.githubusercontent.com/u/657779?v=3","gravatar_id":"","url":"https://api.github.com/users/greg0ire","html_url":"https://github.com/greg0ire","followers_url":"https://api.github.com/users/greg0ire/followers","following_url":"https://api.github.com/users/greg0ire/following{/other_user}","gists_url":"https://api.github.com/users/greg0ire/gists{/gist_id}","starred_url":"https://api.github.com/users/greg0ire/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/greg0ire/subscriptions","organizations_url":"https://api.github.com/users/greg0ire/orgs","repos_url":"https://api.github.com/users/greg0ire/repos","events_url":"https://api.github.com/users/greg0ire/events{/privacy}","received_events_url":"https://api.github.com/users/greg0ire/received_events","type":"User","site_admin":false},"created_at":"2016-04-23T14:28:03Z","updated_at":"2016-04-23T14:28:03Z","body":"BTW, I don't know what is the point of the AdminInterface : \r\n\r\n- no one is going to implement it without extending the `Admin` class\r\n- it violates the ISP so hard, no one is going to want to implement it."}}