Lester,
I understand that IDEs are doing a nice job over the toolset already
created around documentation. That's what phpdoc and friends do.
Also, if you take PHPStorm, it also helps you add Doctrine annotations with
ease. But this is just one IDE, and that's what they're supposed to do;
help developers to code faster with fewer keystrokes.
All docblock annotations support, such as PHPUnit, Doctrine, Addendum,
php-annotations, etc (but with the except of documentation frameworks, like
Doxygen, phpdoc, etc) were created to address a lack of support in the
language itself. Doctrine didn't want to start an Annotations project if
the language already supported, and we even attempted to add this support
to the language back in 2010, which got rejected.
Now time flies and annotation frameworks have mature enough that multiple
codebases are relying on them to help with very day problems, such as
validation, which is what you're referring. phpDocumentor is a purely
strict documentation framework, and that's why it doesn't provide
validation support.
In any case, the usage of docblock for annotations is very bad because it's
extremely error prone. IDEs are helping users, providing autocomplete, but
nothing better than a native language support to validate your annotation
input. Also, there is a fundamental problem of taking docblocks as the rule
to thumb for annotations. Most people just blindly ignore it, but at least
Doctrine team already had to handle this problem educating users multiple
times.
In PHP, to create a docblock you have to start with /** and end with */;
anything inside is considered as text. We also know that most people align
the docblock lines with an idented *. Now to illustrate the problem I want
to provide a mathematical operation *. Here is a sample docblock:
/**
* @Some\Annotation(5 * 8)
*/
This is easily understood as a quick operation of 5 * 8. However, look at
the next example:
/**
* @Some\Annotation(5
* 8)
*/
Or this one:
/**
* @Some\Annotation(5
* *
* 8)
*/
While this might not sound clear, but the docblock parse would have to
consider either the second example or the third example invalid. If you
consider that user must not add a *, then second example is 5 * 8, while
third is 5 * * 8, which is wrong.
Things get a little more tricky when you consider multiline strings. A
couple examples:
/**
* @Some\Annotation("This
* is a
* multiline string")
*/
/**
* @Some\Annotation("This
* is a
* multiline string")
*/
/**
@Some\Annotation("This
is a
multiline string")
*/
/**
* @Some\Annotation("The result of 5
* 8 is 40")
*/
Assuming I'm removing the new line of all examples now, just to reduce
email size and more clarity...
The first example is "This is a multiline string" or "This * is a *
multiline string"?
Let's say we also add more tricks in the parser (like Doctrine did) to
ignore idented * + 1 space. In second example, is it "This is a multiline
string" or "This is a multiline string". Did you notice that now the
spaces now inside of this string in the dockblock may/might matter?
In the third example it is basically what I highlighted on first one... "The
result of 5 * 8 is 40" or "The result of 5 8 is 40"?
Dockblock parsing is hard, unpredictable and may generate a lot of edge
cases. It's just not worth trying to determine all possible conditions
users may face.
Regards,
On Fri, Apr 29, 2016 at 11:18 AM, Lester Caine <les...@lsces.co.uk> wrote:
> On 29/04/16 14:51, Rowan Collins wrote:
> > Lester Caine wrote on 29/04/2016 14:18:
> >> But where will annotations like @range(0,110) fit in the new model?
> >> Along with the likes of '@notnull' and similar annotations that are also
> >> currently being planned to be spread around the rest of the code? If a
> >> variable is defined via the metadata as 'not null', then assigning null
> >> to it is an error
> >
> > Hi Lester,
> >
> > Do you mean you are currently using these attributes / annotations with
> > a reflection library to generate assertions in the code and throw errors
> > at runtime? If so, yes, the native syntax will be used for that going
> > forward, once the tools catch up (though they're likely to provide
> > backwards compatibility modes for a fairly long time).
>
> I think that is part of the problem here. IDE's are currently making
> quite good use of existing annotation text, but if they have to be
> switched to modes where some other option takes priority then once again
> all the code has to be reworked ... which is where I'm stuck at the moment.
>
> > However, there's no support built into the core for doing the actual
> > checks now, and there's no plan (that I know of) to build one in in
> > future. All that's proposed is to add more support in the language for a
> > general syntax which can be used by such tools, to avoid them doing so
> > much string parsing.
> >
> > If you're just using these annotations for documentation (as your
> > references to phpDocumentor imply), then nothing will change: you'll
> > still be able to use them for that, and they still won't be enforced.
> > This is exactly the same as has been true since PHP 5.0 for argument
> > types; the engine never validates anything in the docblock, and it might
> > be completely wrong, and we have separate syntax for actually enforcing
> > checks:
>
> I was looking at php-annotations having realised that it already had
> @range which is the bit I'm trying to automate more. Except it doesn’t
> ... it has stripped the data validation annotations 'because
> phpdocumentor2 does not support them'. HENCE asking the question about
> this important area here ...
>
> > /**
> > * @param Foo $foo
> > */
> > function test(Bar $bar) {}
> >
> > Even if there were no other downsides to the syntax, it would probably
> > be a bad idea for the core to start enforcing things based on docblocks,
> > because it would potentially break a lot of code that had them written
> > wrong. Indeed, it is for precisely this reason that a new syntax is
> > being proposed for general machine-readable attributes (rather than just
> > functions for parsing the docblock), so that we can return to seeing
> > docblocks as just comments, with no meaning for the code.
>
> To repeat ... what happens where an IDE has code with both styles of
> working? You are exactly right but does adding something extra ACTUALLY
> make life easy where we have well documented code and IDE's which
> support it.
>
> > In short:
> > - if you're generating documentation from docblocks, it's up to the
> > program doing the generating what to interpret, and nothing is going to
> > change that
> > - if you're generating behaviour from docblocks, it's up to the library
> > doing the generating what to interpret, and what will change is them
> > recommending the new dedicated syntax if it's implemented, because it
> > will be more efficient to process
>
> As with 'strict typing' we add different styles of working which in some
> longer term world may be an elegant solution but short term just creates
> an annoying different way of doing a bit of the job? The current
> proposal is offering a fix for a style of working which I still don't
> understand, because I can't 'read' easily the examples being given.
>
> <<test("$a + $b > 0")>>
> function foo($a, $b) {
> }
>
> *I* would expect to be checking the range of $a and $b before adding
> some checks combining the data. What is so good about 'test' that adding
> an error check inside 'foo' along with the range checks does not
> provide? I would expect to ALSO have this limit documented within the
> docBloc code anyway as that can include the reason which is absent from
> the above example! The comments go hand in hand with the validation so
> why not keep them together?
>
> --
> Lester Caine - G8HFL
> -----------------------------
> Contact - http://lsces.co.uk/wiki/?page=contact
> L.S.Caine Electronic Services - http://lsces.co.uk
> EnquirySolve - http://enquirysolve.com/
> Model Engineers Digital Workshop - http://medw.co.uk
> Rainbow Digital Media - http://rainbowdigitalmedia.co.uk
>
> --
> PHP Internals - PHP Runtime Development Mailing List
> To unsubscribe, visit: http://www.php.net/unsub.php
>
>
--
Guilherme Blanco
Lead Architect at E-Block
