On Fri, Apr 29, 2016 at 2:36 PM, Rowan Collins <rowan.coll...@gmail.com> wrote:
> Lester Caine wrote on 29/04/2016 13:02: > >> In my book this is DIRECTLY relevant to the current discussion! >> >> We have been adding attributes via docBloc annotation since PHP4 days. >> This has partly been accepted as the default way of doing it and phpDoc >> was originally part of the PEAR support structure. A large section of >> legacy code has well written phpDoc annotation and simply adding the >> current requested attributes to that platform creates no work in the >> core code. >> > > I think there is a misunderstanding here about what code > attributes/annotations are for, and it's understandable given current > practises. > > For instance, you might see a block that looks like this: > > /** > * This is a very cool method. > * @param string $input A stringy thing > * @return boolean Success > * @Magic(42) > */ > public function foo($input) > > Here we have two tags for generating documentation (@param and @return) > and one intended to be accessed via Reflection and add some special > behaviour (@Magic(42)). It is only the behavioural tag that we are > discussing when we talk about "attributes/annotations". > > > In Java, the same block would be in two different parts: > > /** > * This is a very cool method. > * @param input A stringy thing > * @return Success > */ > @Magic(42) > public boolean foo(string input) > > Or in C#: > > /// <summary> > /// This is a very cool method.</summary> > /// <param name="input">A stringy thing</param> > /// <returns>Success</returns> > [Magic(42)] > public boolean foo(string input) > > > Note that the "Magic(42)" uses different syntax, built into the language, > while the documentation parameters stay in comment syntax, and are mostly > just a convention followed by documentation tools. This is what is being > proposed for PHP: > > /** > * This is a very cool method. > * @param string $input A stringy thing > * @return boolean Success > */ > <<Magic(42)>> > public function foo($input) > > > Thus the behaviour of docblocks is not going to change, and reading their > content remains the responsibility of whatever tool you use to generate > documentation from them. The core code has no responsibility for defining > them, and cannot force the developers of documentation generators to treat > them in any particular way. This. Lester, nobody wants to move phpdoc out of the *doc* comment. Its still documentation. It will stay,. We want to move the "annotations" out of the docblocks that are evaluated at runtime for configuration. Thats two different things. That is what the attributes RFC is for. > > > Regards, > -- > Rowan Collins > [IMSoP] > > -- > PHP Internals - PHP Runtime Development Mailing List > To unsubscribe, visit: http://www.php.net/unsub.php > >
