Support for enumerated options fro properties and method arguments

[MarkBaker]

PHPDocumentor doesn't support listing of enumerated values for a property or for a method argument. I suggest that this would be a useful addition to doc blocks;

/*
 * Object State
 *
 * @var string
 * @options=["open", "closed", "pending"] 
 **/ 
private $_state;

/**
 * Set Object State
 *
 * @param string $plotType
 * @options=["open", "closed", "pending"] 
 **/
public function setPlotType($plotType = '') {
    ...
}

While @options might not be the best tag to use, or this syntax could be simplified (and might need modification if the list of options was to be a list of valid constant values), it seems to me that it would be a useful addition to the doc block because the alternative is documenting it in the general block comments. A formal syntax of some description would simplify this and provide a standardised display of the valid options

[boenrobot]

IMHO, it's a better practice to define (class) constants, and then explicitly clarify in the description that acceptable values are one of said constants.

But disregarding that bit... Consider scenarios with multiple arguments, where you have multiple @param tags, followed by one @options. What does @options apply to? The first argument, or the last one specified by @param?

I think it would make much more sense to somehow embed enumerations within the type specification. The pair "[]" is already in use for array specifiers, so either "{}" or "()" should be used, e.g.

/**
 * Set Object State
 *
 * @param string("open", "closed", "pending") $plotType
 **/
public function setPlotType($plotType = '') {
    ...
}

or

/**
 * Set Object State
 *
 * @param string{"open", "closed", "pending"} $plotType
 **/
public function setPlotType($plotType = '') {
    ...
}

Even assuming you accept this variation, I would bet that this wouldn't be trivial to implement (although I don't know for sure, @mvriel would have to be the one to say that), especially considering that constants and other scalar values should also be valid enumarations... So it would probably be pushed for 2.1.

[mvriel]

I was thinking about this issue and perhaps we should expand the scope and think about that. If you take a step back you'd consider that we have a definition of a boundary; something describing the limits of the given data type.

My initial idea would be that we can approach this from two angles:

1. have a new element that defines boundaries for an @var or @param tag or
2. expand the current @var or @param's type to include boundary information (imo: @options might be too abstract)

With boundaries I do not just mean a limited enumeration but also a value range (i.e. [0..3]), array structure or other type of information that limits the possible amount or structure of values contained in the @var or @param.

Downsides:

1. a @var or @param may have more than 1 type (i.e. string|int) or even an array with composed type (i.e. (int|string)[]); how do we designate which to apply the boundary to?
2. A boundary might get too complex (rigid array structure for example) to include in the Type information

In either case we might need a good way of presenting boundaries and existing standards may help out with that

[mvriel]

p.s. if I were to implement this myself I'd consider it for 2.1+; if this item is contributed then I'd be happy to include it in 2.0

[MarkBaker]

In all the cases where I'd be using this (at the moment), the option set would be a series of pre-defined class constants, and I do currently identify the set of options in the description. It was merely a question raised on SO this morning that made me think of an actual tag that would allow them to be defined, and where it would then be easier to link each option to the actual const definition in the docs, or to clarify the description in a structured manner.

Logically, (thinking of my suggested @options tag) if there were multiple @params each with their own @options, I'd anticipate alternate @param and @options tags so each @options referred explicitly to the previous @param

Equally, @param string{"open", "closed", "pending"} $plotType would work... it provides a precise structural definition.

There's also a couple of instances I can think of where a valid value would be a float within a range of -1.0 to 1.0... I hadn't considered using a bounds definition for that, but it is a logical extension from an enumerated set of options.

[boenrobot]

There are already array specifiers, right? So there's no need to worry about that bit.

It's only a matter of specifiers for scalar types (which should extend to those that are part of array specifiers). The "{}" notation would work fine, even for numerical representations, e.g.

@param int{PHP_INT_MIN...-1,1...PHP_INT_MAX} $multiplier
function multiply($multiplier)

Would define $multiplier as expecting (basically) any integer other than 0. Although this here illustrates a new possible extension - a way to explicitly blacklist values rather then whitelist them... perhaps with "!"? Like

@param int{!0,!100} $multiplier
function multiply($multiplier)

would be interpreted as "any integer other then 0 and 100", while

@param int{!PHP_INT_MIN...0} $multiplier
function multiply($multiplier)

would be interpreted as "any non-negative integer".

Damn, this sounds so cool, yet hard...

[mvriel]

There is a discussion going on in PHP-FIG where some of these aspects are touched; might be interesting for this issue

[liverbool]

and associative array?

[boenrobot]

There's a whole other issue (#650) about that, although I guess this here is related as well.

[mvriel]

I have not yet forgotten about this issue but am swamped in other stuff to work on

[liverbool]

+1000 👍

[MarkBaker]

I can fully understand being swamped

[J7mbo]

Did enum ever make it in?

[mvriel]

Hi @J7mbo, they are not included in phpDocumentor2 yet. The discussion on the exact notation and feature set is still on-going

[GameCharmer]

Hello. It's been a year or so since the last comment. Are there any plans for incorporating something like this?

[mikedfunk]

+1

[jaapio]

It doesn't our team is preparing to pick up the discussion on psr-5 again.

[anurbol]

@jaapio that's a good news! I think many people just gave up on this (desired, but not a critical), but they still hoping for it to be implemented. I can speak for myself, I almost switched to node.js/typescript world because of this "little" issue (5 years ago I hated JS for it's messy language, now it's been improved significantly, leaving PHP far behind it)

[igorsantos07]

The more I work with JS, the more I miss the power of its docblocks... Having to resort to IDE-specific annotations (PHPStorm's ExpectedValues) to get this type of feature is just abysmal.

[ashnazg]

I'm very unconvinced on this one. Making a class be your enumerator object seems to me to be the correct approach, both in code and in documenting things. This approach is already supported, and has been back into 1.x.

PHP allowing this behavior (without a proper Enum object) is one of its tradeoffs, and I don't think we can make a doc-only construct for every occasion where "I only want to use strings in my code, but I want my docs to look like these are strict typed thingamabobs".

[anurbol]

These type of issues are the reason why I gave up with PHP after 11 years and moved to node.js + Typescript. PHP is moving too slow for 2018

[gareth-ib]

wow this is a really long time to not do this feature...
If PHP implemented RFC types this would be built in... but they still haven't decided on a good way to do that, so it would be nice if PHPDoc could at least support the idea.

Some sort of concept that would potentially be forward compatible with RFC types being added to php when the figure it out?

    /**
     * @var objectConstants|\Path\To\ClassHoldingStrings
     */
    public $stringFromConstants;

    /**
     * @param objectConstants|\Path\To\ClassHoldingStrings  $param
     */
    public function valueSetter($param) {
        $this->value = $param;
    }

[jaapio]

The thing is not to implement this feature but to maintain al non php constructs in phpdocumentor. We are all looking for a way to fake enum behavior in php. And there are a few good user land implementations on packagist.org following the approach of @ashnazg.

You are now talking about class constants. But remember that class constants are not just string types. It can be an array to. And maybe in the future other complex types.

It is not the task of phpdocumentor to add new language constructs. I think an library in php should fix this issue. If there is a need to add some documentation part to support that library we are happy to provide support. But for now it isn't on our priority list. As it wasn't the last six years.

We already have enough missing features that are added to php. Let us focus on that first before we start making new things in the application.

This issue is open for future reference. And at some point we will start implementing a solution.

[gareth-ib]

yeah I agree there shouldn't be hacks added into phpdoc.. but there must be some sort of concept that can logically solve this concept of needing a param to be a restricted list string, somehow

[Roy-Orbison]

So now that it's PSR-19 any chance of something sane being suggested to the FIG by someone who can?

I really like the type addendum style, but with | for consistency with other PHPDoc conventions:

@param string{'open'|'closed'|'pending'} $plotType

[AmirrezaNasiri]

Hi guys, any update on this? 🤐

[JakeQZ]

@JakeQZ referenced this issue 2 hours ago
Psalm #778

The referenced comment is not properly linked by GitHub (from a large PR and not easy to find o/w), the relevant link is MyIntervals/emogrifier#778 (comment)

[barbu110]

Anything on this yet?

[mvriel]

@ashnazg is this currently in PSR-5/PSR-19? Does this require action?

[quazardous]

how does it looks like ?

In SF there is something like that:
https://symfony.com/doc/5.x/reference/constraints/Choice.html

So my 2 cents :)

use John\Doe\Foo;
...
/**
* @var string{"bar1", Foo::SPECIAL_BAR, ...Foo:LIST_OF_BARS}
*/
public string $bar;

[igorsantos07]

Hm... Twelve years so far and something ""this simple"" (from the end user POV) is still stuck with no ETA so far?

I got surprised that PSR-5 even exists, and is stuck as well as a proposal. I wonder if the PHPDoc specification should evolve independently of its implementations, as it looks like the old PhpDocumentor is dragging the entire community down, when rarely being used now in the age of IDEs and auto-completion. It's not a surprise such tools are hardly ever used to document open-source libraries, for instance.

As mentioned before, there are some basic features missing from PHP docblocks that are a staple when you get used to working with JS: two that come to my mind are @example and list of allowed values. Even if we land on only allowing Enums (which exist for almost 3 years already), this blocks anything written before PHP8 to be properly documented, requesting rewrites to be documented.

[jaapio]

I'm not sure I get your criticism about this topic, but I will give a try to explain from what I understand from your message.

As maintainer of phpDocumentor I'm the first to admit that we are not always keeping up with the rest of the eco system. And to be completely fair... when I say "we", it's mostly me. and before that we also had a very small group of people dragging things forward.

PSR-5 was started years ago to try to get a standard for phpDoc, fact is... there is none. the phpDoc notation used by every tool in the php eco system was and is based on what this project designed 25 years ago. New notations have been added and especially when php started to use static analysis tools more notations have been added. From my point of view, it has been gone wild. Without any guidance. That's exactly we wanted to avoid when we started writing PSR-5. The PSR lost everyone's interest. Again it was a member of this project who tried to drag it forward. But we do not get any support from the rest of the eco system. If we (phpDocumentor) are the only party interested in such a standard, why would we put energy in it?

Fact is, today phpDocumentor supports most of the type notations used by PHPStan and psalm including enums, constants and literal strings. But as it is a lot of work to implement all this into the code our documentation is lagging behind. As I said in the introduction I'm currently the only maintainer of this project. And I have to make choices... my time is limited. Where other projects have more people working on those tools. Documentation isn't a very sexy topic to work on. We see this everywhere, even the new tools introduced in PHP are not documented very well.

---

Back to this issue, today phpDocumentor v3.5 supports literal strings. So a docblock like this would work:

/** 
 * @param "VALUE_1"|"VALUE_2"|"DEFAULT"|false $myParam You can specify a description here
 */

Which covers exactly what was requests... it's never documented nor standardized. By now phpDocumentor is more following others than leading.

---

I hope I did answer your question, and explained a bit more about the way this project is kept alive. I'm sorry if this response makes you feel offended.

[JakeQZ]

type notations used by PHPStan and psalm including enums

IIRC correctly, Psalm (and probably also PHPStan) support 'options' - you can specify a precise set of values that a parameter (such as a string or int) is allowed to be. Without looking it up, I can't quote the exact syntax.

I'm not sure if either (yet) allow comments for the options. But I think that would be the way forward re the OP.

It's an evolving ecosystem. 12 years isn't that long, considering it took Firefox 25 years to fix a significant bug with textarea control sizing :)

Re @example, as long as triple-backticks for code formatting work, I would consider this higher-hanging fruit (nice to have, but you can just type "For example").

Documentation isn't a very sexy topic to work on.

Colleagues have even suggested it may be unnecessary given modern IDE's navigation powers. But that involves downloading all the source code, blah blah blah. Much more convenient to have a web/HTML version available to quickly reference, particularly if you are considering using a package and want to see how it works without downloading, or even if you are a maintainer and want to quickly look up something to answer a question.

Can you come up with a parody of the Right Said Fred song? I've had a stab at the intro:

I'm too sexy for my docs
Too sexy for DocBlocks
Blocks' going to leave me

;)

[jaapio]

If you look at the phpDocumentor code bases you will see that docblocks are omitted and only added when native types are not sufficient. So yes they get a different purpose.

[JakeQZ]

docblocks are omitted and only added when native types are not sufficient.

We do the same. Also, if native types cover some arguments, we may have a DocBlock omitting some, but not all of them, which may be confusing.

The point of the DocBlock is now more clearly to provide additional human-readable information, and presently, a nesting place for Psalm/PHPStan type annotaions, until PHP 9/10 supports them natively...