Documenting packages within a library?

[dharkness]

Note: I understand "package" is a loaded word and is typically synonymous with a library or Composer package, but here I mean part of a larger library as implied by the @package tag.

As a library grows, it is very common to organize the classes into packages. Is there any existing or planned provision for documenting these packages similar to Java's package-info.java file? This documentation would appear on the page listing all classes or namespaces in a folder hierarchy.

We currently choose a class to represent the face of each package and place additional documentation there, but it's not ideal and is easy to miss in a large package. Is there a better way?

[ashnazg]

The @package tag has always been an organizing mechanism in phpDocumentor, that was effectively displaced when proper namespacing was added into PHP. Nowadays, the namespacing itself acts as the code organizer.

This means that @package is available as a separate organizer, and could be the organizer that you're looking for. For documentation itself to be organized this way, you'd likely have to generate your docs at once from a sandbox where all your libraries are together, but that's an implementation detail of the doc generator itself.

On your direct question about a package-info.java equivalent, no, there is not some plan equivalent to that.