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.
Regards,
--
Rowan Collins
[IMSoP]
--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php
