{"action":"created","issue":{"url":"https://api.github.com/repos/phpDocumentor/fig-standards/issues/124","repository_url":"https://api.github.com/repos/phpDocumentor/fig-standards","labels_url":"https://api.github.com/repos/phpDocumentor/fig-standards/issues/124/labels{/name}","comments_url":"https://api.github.com/repos/phpDocumentor/fig-standards/issues/124/comments","events_url":"https://api.github.com/repos/phpDocumentor/fig-standards/issues/124/events","html_url":"https://github.com/phpDocumentor/fig-standards/issues/124","id":127799174,"number":124,"title":"Clarification on Annotations","user":{"login":"dharkness","id":341319,"avatar_url":"https://avatars.githubusercontent.com/u/341319?v=3","gravatar_id":"","url":"https://api.github.com/users/dharkness","html_url":"https://github.com/dharkness","followers_url":"https://api.github.com/users/dharkness/followers","following_url":"https://api.github.com/users/dharkness/following{/other_user}","gists_url":"https://api.github.com/users/dharkness/gists{/gist_id}","starred_url":"https://api.github.com/users/dharkness/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/dharkness/subscriptions","organizations_url":"https://api.github.com/users/dharkness/orgs","repos_url":"https://api.github.com/users/dharkness/repos","events_url":"https://api.github.com/users/dharkness/events{/privacy}","received_events_url":"https://api.github.com/users/dharkness/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":1,"created_at":"2016-01-20T22:28:03Z","updated_at":"2016-08-11T17:57:55Z","closed_at":null,"body":"The last four paragraphs of section 5.3 Tags is a little unclear to me. I think I understand the main point--and I've used actual annotations in other languages and those described here for PHPUnit, etc--but I feel it could use some further clarification. I'll take a stab at a pull request, but first I'd like to make sure I know exactly what is intended.\r\n\r\n1. Annotations are for use by other tools. While they may *look* like tags, they differ because they cannot have a description.\r\n\r\nIs the lack of a description *really* the determining factor of which tags are actually annotations? Won't PHPDoc processors simply ignore tags they don't understand? If they can't understand the tag, how can they hope to parse the full entry to determine whether or not it has a description?\r\n\r\nFor example, declaring a code coverage target:\r\n```\r\n/**\r\n * @covers MyClass\r\n */\r\n```\r\nHow will the parser know that \"MyClass\" is not a description and the tag should be ignored because it's an annotation? I would think it easier to ignore every tag the parser doesn't understand. Of course, it would be nice for the parser to warn the user in case it's a typo:\r\n```\r\nDid you mean @return instead of @covers?\r\n```\r\nAlso, it seems very limiting to block tools from allowing descriptions on their annotations. :-1:\r\n\r\n2. What exactly is meant by \"tag signature\"? As far as I can tell, it only means \"a non-PHPDoc tag without a description\". Is there more meaning/syntax implied here? It seems so because it's implied that one can detect one: \"If a tag signature is present...\" How would I know this?"},"comment":{"url":"https://api.github.com/repos/phpDocumentor/fig-standards/issues/comments/239239819","html_url":"https://github.com/phpDocumentor/fig-standards/issues/124#issuecomment-239239819","issue_url":"https://api.github.com/repos/phpDocumentor/fig-standards/issues/124","id":239239819,"user":{"login":"mindplay-dk","id":103348,"avatar_url":"https://avatars.githubusercontent.com/u/103348?v=3","gravatar_id":"","url":"https://api.github.com/users/mindplay-dk","html_url":"https://github.com/mindplay-dk","followers_url":"https://api.github.com/users/mindplay-dk/followers","following_url":"https://api.github.com/users/mindplay-dk/following{/other_user}","gists_url":"https://api.github.com/users/mindplay-dk/gists{/gist_id}","starred_url":"https://api.github.com/users/mindplay-dk/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mindplay-dk/subscriptions","organizations_url":"https://api.github.com/users/mindplay-dk/orgs","repos_url":"https://api.github.com/users/mindplay-dk/repos","events_url":"https://api.github.com/users/mindplay-dk/events{/privacy}","received_events_url":"https://api.github.com/users/mindplay-dk/received_events","type":"User","site_admin":false},"created_at":"2016-08-11T17:57:55Z","updated_at":"2016-08-11T17:57:55Z","body":"The terminology is kind of mixed-up.\r\n\r\nIn my point of view, they're all \"tags\", all of which we use to *annotate*, e.g. to *create* \"annotations\" - it's just that some happen to be reserved tags for documentation purposes, while others happen to use a different syntax and are intended for run-time consumption.\r\n\r\nIn practice, many documentation tags (such as `@param` or `@return`) may well get consumed at run-time too, so other than the fact that some names are reserved, there really shouldn't be too much of a difference. I don't know why two different terms are required.\r\n\r\nIn [php-annotations](https://github.com/php-annotations/php-annotations) we got around this by treating all tags the same, but the ones that don't use the php-like `@foo('bar')` syntax, such as a standard `@param Foo $bar baz` tag, require a custom parser, such that special tags may have custom syntax, so as to support php-doc annotations.\r\n\r\nNot sure precisely if or how this idea could be carried over the standard, since we do not wish to define syntax or rules for annotation-types not defined by the standard. We can't, really. There are already different annotation systems using different syntax...\r\n"}}
{"actor":{"display_login":"mindplay-dk"}}