search

phpDocumentor / fig-standards

Standards either proposed or approved by the Framework Interop Group
http://www.php-fig.org/
Other
361 stars 85 forks source link

Clarification on Annotations #124

Closed dharkness closed 5 years ago

dharkness commented 8 years ago

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.

  1. Annotations are for use by other tools. While they may look like tags, they differ because they cannot have a description.

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:

/**
 * @covers MyClass
 */

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:

Did you mean @return instead of @covers?

Also, it seems very limiting to block tools from allowing descriptions on their annotations. :-1:

  1. 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?
mindplay-dk commented 8 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...

ashnazg commented 5 years ago

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.