Documenting properties of object-like arrays #3787
Description
We currently use phpDoc nested types to document and type object-like arrays throughout our various codebases, e.g:
/**
* @param array $options {
* @type string $build_path Absolute file system path to the static asset output folder.
* Optional; defaults to the manifest file's parent folder.
* @type string $handle The handle to use when enqueuing the style/script bundle.
* Optional; defaults to the basename of the build folder's parent folder.
* @type array $scripts Script dependencies. Optional.
* @type array $styles Style dependencies. Optional.
* }
*/To better match Psalm's typing, we're looking at instead switching to the object-like array syntax that Psalm supports. This would gain us the typing, but it appears there's no way to retain the human-readable descriptions at the same time with this.
The convention in TypeScript that I've seen is usually something like:
type Foo = {
// This describes the `some` property.
some?: value;
/** Or maybe an inline doc comment */
bar: Quux;
};These don't work in Psalm (and the doc-comment style would break anyway), but a similar style could perhaps be applied. Perhaps something like:
/**
* @return array{
* // Optional docs?
* optional?: string,
*
* # Or this?
* bar: int
* }
*/Is there a recommended solution to this that I've just missed? 🤔