Documentation issue: Separator characters and the @package tag

[henrywright]

This bug report doesn't relate to the application; instead, the report relates to the documentation for the @package tag and more specifically the separator character used.

Here the documentation notes the underscore character can be used as a separator in the same way as the backslash:

Aside from the backslash (), phpDocumentor also allows the underscore (_) and dot (.) as separators for compatibility with existing projects. Despite this the backslash is RECOMMENDED as separator.

To me this indicates _ and \ are equivalent.

Here though, the documentation has an example which uses the underscore character in the package name:

/**
 * class bluh
 * class-level DocBlock example.
 * @package applies_to_bluh
 */

To me this indicates _ isn't quite the same as \ because in this case _ isn't being used as a level "separator"; instead, _ is part of the top level name.

[mvriel]

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

[henrywright]

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
 \

[mvriel]

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

[henrywright]

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

[mvriel]

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?

[henrywright]

Thanks @mvriel and thanks @jaapio for looking

[battis]

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?