Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Conversation

@ramsey
Copy link
Contributor

@ramsey ramsey commented Aug 11, 2022

This PR adds support for PHP enumerations.

In general, the :php:enum: and :php:case: directives work just like :php:class: and :php:const:, respectively. However, to support backed enums, I got a little creative and introduced a minor new syntax to the signature line.

Here's a very simple, basic enum example:

.. php:enum:: Suit
    .. php:case:: Hearts
    .. php:case:: Diamonds
    .. php:case:: Clubs
    .. php:case:: Spades

Here's the same example as a backed enum:

.. php:enum:: Suit : string
    .. php:case:: Hearts : 'H'
    .. php:case:: Diamonds : 'D'
    .. php:case:: Clubs : 'C'
    .. php:case:: Spades : 'S'

This new syntax is effectively the same as this:

.. php:enum:: Suit() -> string
    .. php:case:: Hearts() -> 'H'

The use of () ->, however, is intended to convey method parameters and a return type, which isn't appropriate semantics for a backed enum type and case values, so I decided to introduce this new syntax.

When it renders, Sphinx displays it with the arrow symbol (→) as if it is a return type, but we don't have much choice, since we must use one of the methods from sphinx.addnodes, and I chose to use desc_returns().

Screen Shot 2022-08-10 at 19 36 54

@markstory
Copy link
Owner

Here's the same example as a backed enum:

I think this is very reasonable syntax. docutils is big on : as separators so using it for enum name/values seems inline with other extensions I've seen.

@markstory markstory merged commit 2ea7883 into markstory:master Aug 11, 2022
@ramsey ramsey deleted the enum-support branch August 11, 2022 04:21
@ramsey
Copy link
Contributor Author

ramsey commented Aug 11, 2022

Thanks! 🎉

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants