Comments (7)
The first link you provided is for phpDocumentor 3.x and the latter is for phpDocumentor 1.x - the behaviour of the @package
tag has evolved throughout the years because of the introduction of namespacing and from the community as projects, such as Zend Framework, had adopted the use of the _
in the @package
name as a namespace separator before namespaces were introduced in the PHP language.
Unless I am missing the point here, I am not sure what we can change as there is a difference in how phpDocumentor 1 and 3 operate with this tag
from phpdocumentor.
Thanks for the explanation @mvriel. If phpDocumentor 3 considers the underscore character a level separator, wouldn't code written for phpDocumentor 1 be somewhat broken?
phpDocumentor 1
- Level 1: applies_to_bluh
\**
* @package applies_to_bluh
\
phpDocumentor 3
- Level 1: applies
- Level 2: to
- Level 3: bluh
\**
* @package applies_to_bluh
\
from phpdocumentor.
You are not incorrect! This is a trade-off and is one of the reasons we introduced this in phpDocumentor 2 (thus with a new major version). So far we haven't seen issues with this way and benefits in projects that did use this as namespace separator; but if there is enough demand we could consider a backwards compatibility setting? But so far I haven't heard about a real life use case where this was considered an issue
from phpdocumentor.
I do know the underscore char is encouraged in package naming when extending WordPress with themes and plugins. For example, it isn't intended as a level separator.
Third-party plugin and theme authors must not use @Package WordPress in their plugins or themes. The @Package name for plugins should be the plugin name; for themes, it should be the theme name, spaced with underscores: Twenty_Fifteen.
Source: https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/
There may be more real life examples but I can't think of any
from phpdocumentor.
I am reopening the issue and asking @jaapio to take a look; he has more contact with Wordpress and other parts of the community. Perhaps I am even telling something that is out of date?
from phpdocumentor.
Thanks @mvriel and thanks @jaapio for looking
from phpdocumentor.
An addendum here: the behavior needs to be more fully documented in general, since it's not just the current \
namespace separators and the Zend-style _
that are being treated as separators here. Looking at phpDocumentor\Compiler\ApiDocumentation\Pass\PackageTreeBuilder::normalizePackageName()
, you can see that -
and []
are also being used as separators. And any non-alphanumeric characters are stripped out of package names, to boot.
Given that, in the Packagist world, -
a is perfectly normal character to have in a package name, and knowing that there's also a very real desire to be backwards compatible towards existing packages...
Would it make sense to provide some sort of configuration option to identify the package and/or namespace separator(s) in use in a project?
from phpdocumentor.
Related Issues (20)
- PhpDocumentor creating in pdf HOT 5
- Which tag to use when using constructor property promotion
- Doesn't document the right inherited method HOT 3
- Issue with copy images to output directory
- Revisit writers
- PHP Deprecated: Please use getType in .../phpDocumentor/Descriptor/Traits/CanHaveAType.php HOT 1
- Xdebug has detected a possible infinite loop - problem with latest, not with 3.4.1 HOT 4
- Bug XmlUtils.php - Start tag expected HOT 2
- Twig v3 support? HOT 2
- Background colour is not defined, but text colour is
- Latest git master is pushed to docker hub instead of stable release HOT 3
- feat: render readthedocs flyout menu for default theme HOT 1
- Specify PHIVE install GPG keys HOT 4
- Separate by folder HOT 2
- Document how to create phar
- Doesn't document the right inherited method HOT 1
- Specify a bookmark for `@see`
- Deprecated: Creation of dynamic property HOT 1
- Slowdowns on documentation site generated by PHPDocumentor
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 phpdocumentor.