psr 19. fix incorrect abnf definition

[Google user]

i'm not an expert in this area, but afaik the abnf, current abnf definition of phpdoc contains errors:

PHPDoc             = [summary] [description] [tags]
summary            = *CHAR (2*CRLF)
description        = 1*(CHAR / inline-tag) 1*CRLF ; any amount of characters
                                                 ; with inline tags inside
tags               = *(tag 1*CRLF)
inline-tag         = "{" tag "}"
tag                = "@" tag-name [":" tag-specialization] [tag-details]
tag-name           = (ALPHA / "\") *(ALPHA / DIGIT / "\" / "-" / "_")
tag-specialization = 1*(ALPHA / DIGIT / "-")
tag-details        = *SP (SP tag-description / tag-signature )
tag-description    = 1*(CHAR / CRLF)
tag-signature      = "(" *tag-argument ")"
tag-argument       = *SP 1*CHAR [","] *SP

https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc.md#532-tag-specialization

it doesn't DEFINE the phpdoc because it allows the incorrect character sequences. examples follow.

e.g.'summary'. it is defined as any chars. does it mean that the following is a correct summary?

{@}*/

it IS a sequence of any chars, followed by two crlfs, thus it matches the 'summary' definitiion. but as you may see, it closes the php comment block, thus it cannot be a valid phpdoc at all.

example 2. description has the same bug.

this abnf definition lacks such classes as 'reserved characters' and the definition of when and how they may or may not appear and in which way they must be escaped if needed. e.g., see the uri specification rfc 3986 as an example.

example 3. 'inline-tag' contains 'tag-description' which contains crlf. is it really allowed to use line breaks inside the inline tags?

example 4. 'tag-signature' contains any number of 'tag-argument's, and 'tag-argument' may contain a comma, but each tag argument MUST have at least 1 char. does that mean that a comma itself doesn't count as an argument? but such definition DOES allow the tag-signature be: (a,b,), i.e. the last argument is missing, is it really allowed? also, is it really allowed not to use commas and spaces at all: (arg1arg2)? (cause all SP and commas a optional here)

or should it be:

tag-signature      = "(" [ tag-argument *(*SP "," tag-argument) ] ")"
tag-argument       = *SP 1*CHAR *SP

etc, i'm sure i could continue, but don't want to spend more time on it, i think it's enough to see the main idea.

i mean that this definition isn't precise. if i'll make a parser which will use exactly this definition as a grammar definition, then this parser will match incorrect char sequences and report them as a correct phpdoc, while they aren't

imo, the abnf definition must either be precise, or absent at all, do you agree?