Closed dharkness closed 5 years ago
The terminology is kind of mixed-up.
In 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.
In 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.
In 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.
Not 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...
Please see the current version at https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md#531-tag-name , and reopen this if your question still applies.
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.
Is 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?
For example, declaring a code coverage target:
How 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:
Also, it seems very limiting to block tools from allowing descriptions on their annotations. :-1: