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?
--
You received this message because you are subscribed to the Google Groups "PHP
Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/php-fig/97a3cb47-6e41-4ad8-ac3f-3224f2bb96c7%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
