Comments (14)
I wouldn't mind it. I'd also suggest following the PSR proposal and
phpDocumentor/fig-standards#37 specifically as a
tag without the brackets may be introduced. And FWIW, in some code I'm
trying out locally, I started using that tag in place of the "proper" doc
block.
While I'm thinking about it, if there are any issues with our sniffer not
accepting something in the PSR, as it is defined and ratified, we should
adjust our rules to adapt, to include potentially throwing warnings on
deprecated tags.
On Monday, December 23, 2013, Piotr wrote:
Let's consider allowing the {@inheritdoc} tag.
This really helps when extending classes, you don't have to rewrite whole
docblock and keep it up to date with docblock changes in base class.Important bonus is that one can easily see that the method has a parent.
At this moment php code sniffer complains like:
50 | ERROR | Doc comment for "$form" missing
52 | ERROR | Missing @return tag in function commentThis tag is being widely used in projects like Symfony and Drupal.
Usageclass A{
/** * Foo method * * @param array $bar Bar * * @return void /
public function foo(array $bar)
{
}}
class B extends A{
/* * {@inheritdoc} */
public function foo(array $bar)
{
}}References
- javadoc: {@inheritdoc}http://docs.oracle.com/javase/6/docs/technotes/tools/solaris/javadoc.html#@inheritDoc
- phpDocumentor: {@inheritdoc}http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.inlineinheritdoc.pkg.html
—
Reply to this email directly or view it on GitHubhttps://github.com//issues/50
.
from coding-standards.
The PSR isn't yet ratified, it's still in progress.
from coding-standards.
So I'm actually referring to a @inheritDoc
tag, that's not yet part of phpDocumentor.
{@inheritdoc}
is used just for descriptions or @param
's text values.
from coding-standards.
Got that, just saying keep an eye on it as it works through the system,
that's all.
On Mon, Dec 23, 2013 at 11:40 AM, Don Gilbert [email protected]:
The PSR isn't yet ratified, it's still in progress.
—
Reply to this email directly or view it on GitHubhttps://github.com//issues/50#issuecomment-31132581
.
from coding-standards.
You, but I didn't 😄 Thanks for that link, I didn't know I've been using this tag wrong way all the time.
from coding-standards.
I personally don't like the inheritdoc tag because when I'm inspecting the
code I have to work up the inheritance chain to find the documentation.
It's not so bad once you get to know the code but I find it annoying if I'm
trying to learn the API, not to mention evaluate a pull request. This is
something that frustrates me when I look at other frameworks.
Regards,
Andrew Eddie
http://learn.theartofjoomla.com - free tutorials and videos on Joomla
development
from coding-standards.
@eddieajau
I didn't think of this. You are right, this tag makes it harder to learn the API, but easier when working with something you already know.
Does anybody know what is the support in IDEs? If one could see the inherited docblock, I think we could start using it but if not, let's not use it ATM
from coding-standards.
New resources to consider:
- reference to phpDocumentor manual: Basic Syntax > Inheritance
- PSR-5: PHPDoc Standard (DRAFT, WIP)
from coding-standards.
For my experience, PHPStorm cannot show any information of {@inheritDoc}
, I have to trace the parent to see docblock.
I'm agree with @eddieajau, I also don't like this tag. It's my personal opinion.
But I think we can wait for PSR-5
from coding-standards.
After
CodeSniffer/Standards/PEAR/Sniffs/Commenting/FunctionCommentSniff.php:129
We may put:
foreach ($tokens[$commentStart]['comment_tags'] as $tag) {
if (strtolower($tokens[$tag]['content']) == '@inheritdoc') {
$isSpecialMethod = true;
}
[...]
}
It will work. Perhaps this validation is needed to be replaced with customized one.
from coding-standards.
Any progress on this ?
from coding-standards.
For example Eclipse does support it and I guess PHPStorm does as well. It makes no sense to copy doc blocks from the base class. If that doc block changes all the subclasses do need to be updated.
from coding-standards.
I also don't like it personally and would go with @eddieajau on this.
On the other hand I believe that the sniffer should "allow" it so extension devs may use it as they wish.
The code proposed by @andkirby looks good. Maybe a PR would be accepted?
from coding-standards.
Apparently this tag is being supported in PHPStorm since v6 (I can't confirm as I'm not using it).
Joomla is the only framework I've used that doesn't implement it.
from coding-standards.
Related Issues (20)
- [2.x] More Indention Issues With Closures HOT 2
- [4.0] Anonymous class support HOT 5
- [RFC] Multiline Signature Formatting HOT 4
- Analysis.md - 404 error on link from website HOT 2
- support for vscode HOT 8
- Indentation Confusion HOT 1
- Require visibility for class constants HOT 2
- Support new magic methods in PHP 7.4 HOT 3
- phpstorm 2019.2 doesn't follow settings HOT 2
- typos in README
- New Lines in XML-Files
- Indention checks fail with static Closure
- @since -> @SInCE HOT 1
- @headers link to invalid GitHub pages HOT 1
- Can we change standard from <br /> to <br> ? HOT 4
- Documentation - How should database table and column names be written HOT 3
- [PHP8] Document named arguments BC policy HOT 1
- Links in joomla site not working HOT 1
- problem in alternative syntax (controller statements)
- PSR12 mention in README.md
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from coding-standards.