PHPDoc enhancement: @event

[Ryan Parman]

I would like to propose the following enhancement to be included in a future PHPDoc-specific PSR: @event

@event

The @event tag is used to document events that are triggered by this function or method.

## Syntax

@event <"Type"> <"event_identifier"> [description]

## Description

With the @event tag, it is possible to document and event that is triggered by the function or method. When provided it MUST contain a "Type" (See Appendix A) to indicate what is returned; it MUST contain the name of the event that can be subscribed to by an event handler; the description on the other hand is OPTIONAL yet RECOMMENDED.

The @event tag MAY have a multi-line description and does not need explicit delimiting.

This tag MAY occur more than once in a "DocBlock" and is limited to the "DocBlock" of a type method or function.

## Examples

use Symfony\Component\EventDispatcher\Event;

use Vanity\Custom\Event\SimpleEvent;

/**

 * @event Event       vanity.task.all.complete Triggers when all of the tasks have been completed.

 * @event SimpleEvent vanity.task.failure      Triggers when a task fails to complete successfully.

 */

[Patrick Mulvey]

PHP itself does not have any concept of "events". People using event-driven systems in PHP are simulating this behaviour using regular PHP functions and objects. Therefore I think it would be extremely important to define exactly what is meant by an event to avoid confusion. 

[Robert Gründler]

i like Ryans proposal a lot. Although events are not a built-in behavior of PHP, more and more frameworks are using the pattern. While events are a very
useful thing to decouple your code, they also make debugging harder.

Annotating methods that way would enable static code analysis to determine where events are being fired - especially useful if IDEs understand
that annotation and can provide you with useful information about the internals of your app/framework.


-robert

[Mike van Riel]

Having an @event annotation can be really interesting to an Event
Dispatching library, etc. However, I am doubting whether this should
be in the core PHPDoc specification as it only serves a 'small' subset
of users. Wouldn't it be better to define this in another RFC
regarding things that use events?

Or another question; what is it exactly do you want to convey to your
users? Somehow, to me, this seems more appropriate as an annotation
than as a tag.

> --
> You received this message because you are subscribed to the Google Groups
> "PHP Framework Interoperability Group" group.
> To post to this group, send email to php...@googlegroups.com.
> To unsubscribe from this group, send email to
> php-fig+u...@googlegroups.com.
> To view this discussion on the web visit
> https://groups.google.com/d/msg/php-fig/-/TsJuyB8RCfsJ.
>
> For more options, visit https://groups.google.com/groups/opt_out.
>
>

[Ryan Parman]

Conceptually, I see @event being very similar to @throw.

@throw is intended to inform the consumer that a particular method/function MAY throw a particular exception.

Likewise, @event is intended to inform the consumer that a particular method/function may/will trigger a particular event type. By coupling an extension, it allows package authors to more clearly articulate to consumers which event hooks are exposed, allowing them to customize behavior as appropriate.

And to be fair, annotations are no more a first-class citizen in PHP than events are. :)

[Mike van Riel]

I will reply inline:

On Tue, Oct 9, 2012 at 4:43 PM, Ryan Parman <ry...@ryanparman.com> wrote:
> Conceptually, I see @event being very similar to @throw.
>
> @throw is intended to inform the consumer that a particular method/function MAY throw a particular exception.
>
> Likewise, @event is intended to inform the consumer that a particular method/function may/will trigger a particular event type. By coupling an extension, it allows package authors to more clearly articulate to consumers which event hooks are exposed, allowing them to customize behavior as appropriate.

The difference to me is that an event is not a native PHP language
construct but something a userland library could define. As such I
believe that if a userland library uses such an annotation then they
can and should define it, and could even provide an extension for
their favourite documentation generator to process this event (and
even allow such a thing as link to the documentation).

To provide this as a standard PHPDoc tag and not as part of said
userland library feels odd to me and feels as if the PHPDoc Standard
would dictate how userland libraries should consume such a tag.

Having said that, I am however very curious how others see this.

> And to be fair, annotations are no more a first-class citizen in PHP than events are. :)

That is why I used the word; the PHPDoc Standard does not support
annotations. It only supports the syntax as used by several projects
out there so that userland libraries may use that. I see the same
here, the @event tag's syntax is supported but the tag itself may be
adopted by userland libraries.

[Sebastian Krebs]

2012/10/9 Ryan Parman <ry...@ryanparman.com>

Conceptually, I see @event being very similar to @throw.

@throw is intended to inform the consumer that a particular method/function MAY throw a particular exception.

Likewise, @event is intended to inform the consumer that a particular method/function may/will trigger a particular event type. By coupling an extension, it allows package authors to more clearly articulate to consumers which event hooks are exposed, allowing them to customize behavior as appropriate.

And to be fair, annotations are no more a first-class citizen in PHP than events are. :)

Worth to say, that this aren't annotations, but DocCommens, or even further "Just" comments. I don't think either, that it is useful to formalize the way to describe, what is in fact part of 3rd party libraries. We could extend this to @log, @triggerWarning, @cache and so on. Where should it end?

--
github.com/KingCrunch

[Johannes Schmitt]

I agree with Mike.

I see that @event is useful for certain PHP libraries, but that we should not try to put any constraints on how an event library should be implemented. For example, it could be that someone uses an event dispatcher which does not require an Event object.

Johannes

[Ryan Parman]

@Sebastian Krebs:

Where should it end? We already have:

@api

@author

@deprecated

@global

@internal

@package

@since

@todo

Arguably some of these are no more or less valuable/relevant than @event would be. None of these represent PHP constructs -- they're just metadata. :)

[Ryan Parman]

On Oct 9, 2012, at 7:57 AM, Mike van Riel <draco...@gmail.com> wrote:

> On Tue, Oct 9, 2012 at 4:43 PM, Ryan Parman <ry...@ryanparman.com> wrote:
>> Conceptually, I see @event being very similar to @throw.
>>
>> @throw is intended to inform the consumer that a particular method/function MAY throw a particular exception.
>>
>> Likewise, @event is intended to inform the consumer that a particular method/function may/will trigger a particular event type. By coupling an extension, it allows package authors to more clearly articulate to consumers which event hooks are exposed, allowing them to customize behavior as appropriate.
>
> The difference to me is that an event is not a native PHP language
> construct but something a userland library could define. As such I
> believe that if a userland library uses such an annotation then they
> can and should define it, and could even provide an extension for
> their favourite documentation generator to process this event (and
> even allow such a thing as link to the documentation).
>
> To provide this as a standard PHPDoc tag and not as part of said
> userland library feels odd to me and feels as if the PHPDoc Standard
> would dictate how userland libraries should consume such a tag.
>
> Having said that, I am however very curious how others see this.

So, to be clear, are you suggesting that a documentation tool (e.g., phpDocumentor, Vanity, Sami, ApiGen) would define the syntax that such an @event tag would have? Or that the Event package (e.g., Symfony EventDispatcher) would define the syntax?

Would they define "@event", or "@phpDocumentor-event", or "@symfony-eventdispatch-event"? Would this not end up inviting fragmentation and support matrices of [Doc tools * Event libraries]?

Additionally, for the sake of discussion, what is the purpose of the PHPDoc spec? Is it:

* To determine which patterns are native vs. userland? Or...

* To enable developers to provide the best possible documentation experience for their users?

I'll be the first to show my bias in favor of the latter. The event pattern in PHP may be a userland solution, but so was namespacing until 5.4. What I'm suggesting is that if this is an identified pattern being used by PHP developers, then there should be a way to document it for end-users. My suggestion is an @event tag.

To me, it makes sense that we should establish a pattern now in order to avoid a [Doc tools * Event libraries] matrix. By establishing a common pattern for documenting events (i.e., an identified design pattern that developers are already using *today*), we can avoid establishing this in the future when we have more inconsistency to tame.

Thoughts?

[Jeremy Lindblom]

@event? Yes, please!

I've seen several projects already doing this. It makes sense for tools implementing this potential spec to support it, even if there are also many who don't use it.

> ...The event pattern in PHP may be a userland solution, but so was namespacing until 5.4. What I'm suggesting is that if this is an identified pattern being used by PHP developers, then there should be a way to document it for end-users.

Good point. I agree.

--
Jeremy Lindblom
PHP Software Development Engineer & Web Application Developer
Amazon Web Services – AWS SDK for PHP
@jeremeamia • https://github.com/jeremeamia

Looking for work? Help bring the "cloud" to developers. AWS needs
- JavaScript developers: http://www.amazon.com/gp/jobs/173568
- Ruby developers: http://www.amazon.com/gp/jobs/160651
- Python developers: http://www.amazon.com/gp/jobs/173569
- Systems engineers: http://www.amazon.com/gp/jobs/174287

Let me know if you are interested!

[Patrick Mulvey]

On Tuesday, October 9, 2012 5:13:53 PM UTC+1, Ryan Parman wrote:

Additionally, for the sake of discussion, what is the purpose of the PHPDoc spec? Is it:

* To determine which patterns are native vs. userland? Or...

* To enable developers to provide the best possible documentation experience for their users?

I'll be the first to show my bias in favor of the latter. The event pattern in PHP may be a userland solution, but so was namespacing until 5.4. What I'm suggesting is that if this is an identified pattern being used by PHP developers, then there should be a way to document it for end-users. My suggestion is an @event tag.

How exactly are we identifying this pattern? 

 

To me, it makes sense that we should establish a pattern now in order to avoid a [Doc tools * Event libraries] matrix. By establishing a common pattern for documenting events (i.e., an identified design pattern that developers are already using *today*), we can avoid establishing this in the future when we have more inconsistency to tame.

Thoughts?

I agree with this argument. Based on the conversation so far, I'm generally in favor of having an @event tag. 

But you repeatedly mention that event-driven systems are an "identified pattern". Identified by who? What are the characteristics of an "event pattern"? Is there a formal definition somewhere? Since there's no standard implementation of events in PHP, how do we determine where an @event tag is or is not appropriate?

My concern is that people will have differing expectations of what constitues an event, and therefore will use and interpret @event tags in different ways. This has the potential to cause confusion. As you said, the purpose of a documentation spec should be to provide the best documentation experience for users. That won't happen if there isn't a clear definition and solid understanding among developers of what each documentation tag relates to.

[Mike van Riel]

Introducing an @event tag would dictate the way event handling
software are to function and as such do not document but dictate
behaviour.
I personally believe that a separate initiative should be started to
have interoperability between event handling software, such as
Symfony2's Event Dispatcher. This initiative could create a PSR that
allows for their own tags and annotations as a form of DSL; the PHPDoc
Standard supports these additions/extensions.

Ryan, regarding your question; it is beyond doubt that the goal is to
enable developers to write the best documentation out there. But
please keep in mind that that does not mean all patterns should be
included in the core standard.

For example:

Logging is done far more often than event handling; should a @log be
added to indicate this method outputs a log? What about sending
e-mails? Should @email be added?
Where do you draw the line? By adding @event we add responsibility for
governing this and all effects related.

Regarding:

> @api
> @author
> @deprecated
> @global
> @internal
> @package
> @since
> @todo

None of the above define what the current syntactical element *does*,
only meta-information.

I will be the first to admit that selecting which tags to include is
hard but I honestly believe this is too specific for a core
specification.

> --
> You received this message because you are subscribed to the Google Groups
> "PHP Framework Interoperability Group" group.
> To post to this group, send email to php...@googlegroups.com.
> To unsubscribe from this group, send email to
> php-fig+u...@googlegroups.com.
> To view this discussion on the web visit

> https://groups.google.com/d/msg/php-fig/-/uqdzT62xziQJ.

[Sebastian Krebs]

2012/10/9 Mike van Riel <draco...@gmail.com>

Introducing an @event tag would dictate the way event handling
software are to function and as such do not document but dictate
behaviour.

Beside, that I don't like the @event-tag: As far as I understood Ryan only talks about documentation and not that any existing implementation really takes care.

--
github.com/KingCrunch

[Marc Bennewitz]

Personally I don't like the name @event because the method triggering an
event itself isn't an event.
Like @throws describes en exception that may be throw.

A better name would be @triggers or @fires.

Greetings
Marc

On 09.10.2012 16:43, Ryan Parman wrote:
> Conceptually, I see @event being very similar to @throw.
>
> @throw is intended to inform the consumer that a particular method/function MAY throw a particular exception.
>
> Likewise, @event is intended to inform the consumer that a particular method/function may/will trigger a particular event type. By coupling an extension, it allows package authors to more clearly articulate to consumers which event hooks are exposed, allowing them to customize behavior as appropriate.
>
> And to be fair, annotations are no more a first-class citizen in PHP than events are. :)
>
>
> On Oct 9, 2012, at 5:46 AM, Mike van Riel <draco...@gmail.com> wrote:
>
>> Having an @event annotation can be really interesting to an Event
>> Dispatching library, etc. However, I am doubting whether this should
>> be in the core PHPDoc specification as it only serves a 'small' subset
>> of users. Wouldn't it be better to define this in another RFC
>> regarding things that use events?
>>
>> Or another question; what is it exactly do you want to convey to your
>> users? Somehow, to me, this seems more appropriate as an annotation
>> than as a tag.
>>

[Ryan Parman]

On Oct 9, 2012, at 10:52 AM, Patrick Mulvey wrote:

On Tuesday, October 9, 2012 5:13:53 PM UTC+1, Ryan Parman wrote:

What I'm suggesting is that if this is an identified pattern being used by PHP developers, then there should be a way to document it for end-users. My suggestion is an @event tag. 

How exactly are we identifying this pattern?

The event pattern is being used. It didn't occur to be that this would even be in question, but here is the evidence:

https://github.com/search?q=EventDispatch&repo=&langOverride=&start_value=1&type=Code&language=PHP

To me, it makes sense that we should establish a pattern now in order to avoid a [Doc tools * Event libraries] matrix. By establishing a common pattern for documenting events (i.e., an identified design pattern that developers are already using *today*), we can avoid establishing this in the future when we have more inconsistency to tame. 

Thoughts? 

I agree with this argument. Based on the conversation so far, I'm generally in favor of having an @event tag. 

But you repeatedly mention that event-driven systems are an "identified pattern". Identified by who? What are the characteristics of an "event pattern"? Is there a formal definition somewhere? Since there's no standard implementation of events in PHP, how do we determine where an @event tag is or is not appropriate?

In an attempt to bring what sounds like a hypothetical argument and bring in down to real-world implementations, I'm talking about the 800 lb. gorilla: Symfony Event Dispatcher. I recognize that there are other event systems in-use, and I'd love to take those into account as well, but I've been hard-pressed to find them.

Educate me?

My concern is that people will have differing expectations of what constitues an event, and therefore will use and interpret @event tags in different ways. This has the potential to cause confusion. As you said, the purpose of a documentation spec should be to provide the best documentation experience for users. That won't happen if there isn't a clear definition and solid understanding among developers of what each documentation tag relates to.

If this were a hypothetical debate, then sure, I'd agree with you. But how many people do you know who are using events in PHP _without_ using Symfony Event Dispatcher? Now, how many with?

One of the tenets of this group is to attempt to codify things that are already happening in the community. This is something that is clearly already happening in the community.

[Ryan Parman]

On Oct 9, 2012, at 1:02 PM, Mike van Riel wrote:

Introducing an @event tag would dictate the way event handling

software are to function and as such do not document but dictate

behaviour.

I don't necessarily agree, but I'm listening...

I personally believe that a separate initiative should be started to

have interoperability between event handling software, such as

Symfony2's Event Dispatcher. This initiative could create a PSR that

allows for their own tags and annotations as a form of DSL; the PHPDoc

Standard supports these additions/extensions.

So, if I'm understanding you correctly, you're saying that:

1. @event should not necessarily be part of the PHPDoc PSR, but rather a separate PSR?
2. As such, the PHPDoc PSR should/will be compatible with this new PSR?

Is this correct?

I'd be fine with #1, but I don't understand what you mean by #2.

Ryan, regarding your question; it is beyond doubt that the goal is to

enable developers to write the best documentation out there.

I just wanted to make sure. Some of the earlier arguments related to core vs. non-core functionality in PHP, but I wanted to make sure we all understood that there is a very real user-facing issue here.

But

please keep in mind that that does not mean all patterns should be

included in the core standard.

What other standard is there besides the PHPDoc core standard? I'm not aware of anything, but I'm open to ideas.

For example:

Logging is done far more often than event handling; should a @log be

added to indicate this method outputs a log? What about sending

e-mails? Should @email be added?

Where do you draw the line? By adding @event we add responsibility for

governing this and all effects related.

This sounds a bit far-fetched to me. We're reaching too far into hypotheticals when we need to focus on real-world adaptation.

People are *presently* using homegrown @event tags. I don't know of a single instance of @email or @log being used in the wild.

Case-in-point, 3 of our very own member projects are doing this (albeit with a simpler syntax than what I've proposed):

https://github.com/phpbb/phpbb3/blob/develop/phpBB/common.php#L159
https://github.com/zendframework/zf2/blob/master/library/Zend/Mvc/Controller/AbstractController.php#L88
http://flow.typo3.org/documentation/codingguidelines/javascript.html

Regarding:

@api

@author

@deprecated

@global

@internal

@package

@since

@todo

None of the above define what the current syntactical element *does*,

only meta-information.

Perhaps...

I will be the first to admit that selecting which tags to include is

hard but I honestly believe this is too specific for a core

specification.

Noted. I disagree, but I'm open to alternative suggestions.

[Sebastian Krebs]

2012/10/10 Ryan Parman <ry...@ryanparman.com>

On Oct 9, 2012, at 10:52 AM, Patrick Mulvey wrote:

On Tuesday, October 9, 2012 5:13:53 PM UTC+1, Ryan Parman wrote:

What I'm suggesting is that if this is an identified pattern being used by PHP developers, then there should be a way to document it for end-users. My suggestion is an @event tag. 

How exactly are we identifying this pattern?

The event pattern is being used. It didn't occur to be that this would even be in question, but here is the evidence:

https://github.com/search?q=EventDispatch&repo=&langOverride=&start_value=1&type=Code&language=PHP

To me, it makes sense that we should establish a pattern now in order to avoid a [Doc tools * Event libraries] matrix. By establishing a common pattern for documenting events (i.e., an identified design pattern that developers are already using *today*), we can avoid establishing this in the future when we have more inconsistency to tame. 

Thoughts? 

I agree with this argument. Based on the conversation so far, I'm generally in favor of having an @event tag. 

But you repeatedly mention that event-driven systems are an "identified pattern". Identified by who? What are the characteristics of an "event pattern"? Is there a formal definition somewhere? Since there's no standard implementation of events in PHP, how do we determine where an @event tag is or is not appropriate?

In an attempt to bring what sounds like a hypothetical argument and bring in down to real-world implementations, I'm talking about the 800 lb. gorilla: Symfony Event Dispatcher. I recognize that there are other event systems in-use, and I'd love to take those into account as well, but I've been hard-pressed to find them.

A 800 lb. gorilla is not a "standard gorilla" and also there is at least a ZF2-implementation, that is not a tiny, little mouse too ;) Anyway, I don't think it's useful, when this group begins to make preferences about one implementations over others. At the end "the others" will just go away.

 

Educate me?

My concern is that people will have differing expectations of what constitues an event, and therefore will use and interpret @event tags in different ways. This has the potential to cause confusion. As you said, the purpose of a documentation spec should be to provide the best documentation experience for users. That won't happen if there isn't a clear definition and solid understanding among developers of what each documentation tag relates to.

If this were a hypothetical debate, then sure, I'd agree with you. But how many people do you know who are using events in PHP _without_ using Symfony Event Dispatcher? Now, how many with?

One of the tenets of this group is to attempt to codify things that are already happening in the community. This is something that is clearly already happening in the community.

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To post to this group, send email to php...@googlegroups.com.
To unsubscribe from this group, send email to php-fig+u...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

--
github.com/KingCrunch

[Ryan Parman]

On Oct 9, 2012, at 11:12 PM, Sebastian Krebs <kreb...@gmail.com> wrote:

> A 800 lb. gorilla is not a "standard gorilla" and also there is at least a ZF2-implementation, that is not a tiny, little mouse too ;)

By this logic, PHPDoc isn't a standard either... but the truth is, it is -- at least as a _de-facto_ standard. The same could be said for Microsoft Word (in the business world), XMLHTTPRequest (until recently), and other non-standards that we completely take for granted.

Arguably, an 800 lb. gorilla *may* be (at the very least) a de-facto standard.

But nevermind that. That isn't even my intended point...

> Anyway, I don't think it's useful, when this group begins to make preferences about one implementations over others. At the end "the others" will just go away.

I'm genuinely interested in learning about what other event systems are actually seeing real-world use. Even if @event doesn't make it into the formal PHPDoc PSR (as I'd prefer), understanding (a) what else is out there, and (b) how to define a spec that fits them is -- I think -- important.

I chose to start the discussion with Symfony's implementation because that's what I overwhelmingly see in real-world use. But that doesn't mean I want to exclude other packages -- I just don't know what they are.

You mentioned that ZF2 has an implementation. I was unaware of it because I haven't seen any projects using it (yet?), but I'd be happy to take a look and begin refining my initial proposal.

My point is this:

1. Developers are using events in PHP.
2. Developers need a way to *effectively* document events.
3. Users need to be able to understand *how* to leverage the events.

If we can address this need in another way, I'm open to those discussions.

[Patrick Mulvey]

On Wednesday, October 10, 2012 7:47:01 AM UTC+1, Ryan Parman wrote:

On Oct 9, 2012, at 11:12 PM, Sebastian Krebs <kreb...@gmail.com> wrote:

> A 800 lb. gorilla is not a "standard gorilla" and also there is at least a ZF2-implementation, that is not a tiny, little mouse too ;)

By this logic, PHPDoc isn't a standard either... but the truth is, it is -- at least as a _de-facto_ standard. The same could be said for Microsoft Word (in the business world), XMLHTTPRequest (until recently), and other non-standards that we completely take for granted.

You're right, PHPDoc is not a standard. I extensively use ApiGen because I think it's a superior tool. I'm also a business owner who doesn't own Microsoft Word. The point being that I'd prefer it if we didn't attempt to enforce things based on the subjective opinion that they are a de facto standard, because there are valid alternatives that should be considered equal. 

The title of this thread aside, I think the purpose here is to come up with a PSR for PHP code documentation in general, not PHPDocumentor specifically, right?

 

Arguably, an 800 lb. gorilla *may* be (at the very least) a de-facto standard.

But nevermind that. That isn't even my intended point...


> Anyway, I don't think it's useful, when this group begins to make preferences about one implementations over others. At the end "the others" will just go away.

I agree with this - we can't base a standard around one implementation.

The event pattern is being used. It didn't occur to be that this would even be in question, but here is the evidence:

https://github.com/search?q=EventDispatch&repo=&langOverride=&start_value=1&type=Code&language=PHP

I think you misunderstood me. I'm not contesting that people are using event patterns. I was asking how you define an event pattern. How do you distinguish between an event pattern and a non-event pattern? Does an event pattern have to use a defined Event or EventDispatcher class?

My point is that events themselves are non-standard. If we introduce an @event tag, then it too will be a vague, undefined term unless we clarify it. It's also hard to devise documentation tags for a feature that could be implemented in many different ways.

How did you come up with the syntax for @event that you proposed? Why do events need to have both a type and an event_identifier? I can easily imagine an event system that only uses one of those properties for events.

Before we choose a syntax for @event, shouldn't we consider that someone may release an event system that may not resemble current event systems at all? This is why I'm curious as to how we are defining an event pattern, because the @event syntax should be flexible enough to cover any event pattern. Your proposal seems to be based on Symfony's implementation, but I can imagine other ways to manage events that would not be compatible with your proposed syntax.

If this were a hypothetical debate, then sure, I'd agree with you. But how many people do you know who are using events in PHP _without_ using Symfony Event Dispatcher? Now, how many with?

Annovent is another event system that I've seen used. I'm sure there are others. Are you now suggesting that a standard be written around Symfony's implementation of an event, just because it seems to currently be the most popular? I am completely opposed to that idea. 

Personally I don't like the name @event because the method triggering an 
event itself isn't an event. 
Like @throws describes en exception that may be throw. 

A better name would be @triggers or @fires. 

I agree with this - @event would be better used to describe an event object itself (if it's even necessary to define a new tag for that). @fires, @triggers or @dispatches makes more sense for documenting that an event may be dispatched.

[Matthew Lanigan]

I think you misunderstood me. I'm not contesting that people are using event patterns. I was asking how you define an event pattern. How do you distinguish between an event pattern and a non-event pattern? Does an event pattern have to use a defined Event or EventDispatcher class?

The "event pattern" is also known as the "observer pattern" and is a pretty widely pervasive software design pattern.

It is called a "pattern" because it is just that -- an underlying design pattern; it is not the names of the classes involved, or even the interface through which they're accessed (similar to how a pattern is used to cut out the cloth for a piece of clothing -- but doesn't define the cloth or embellishments).

I'm not really sure that the problem you are professing is a problem at all.

Regardless, I agree with the sentiment that an "@event" tag should not be included in the core PHPDoc PSR, but should rather be defined as a PHPDoc extension in a future Event-related PSR -- and this standard of "core" vs. "extension" should also be applied to any non-standard, implementation-related PHPDoc tags in the future.

By leaving open the opportunity for extension by future PSRs, the PHPDoc standard, essentially, gains a level future-proofing that is not insubstantial, and it also allows those extensions to occur without unnecessary bloating of the core PHPDoc PSR.

Matthew Lanigan

--

You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To post to this group, send email to php...@googlegroups.com.
To unsubscribe from this group, send email to php-fig+u...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msg/php-fig/-/6QlcH3c4SEQJ.

[Sebastian Krebs]

2012/10/10 Matthew Lanigan <rin...@gmail.com>

I think you misunderstood me. I'm not contesting that people are using event patterns. I was asking how you define an event pattern. How do you distinguish between an event pattern and a non-event pattern? Does an event pattern have to use a defined Event or EventDispatcher class?

The "event pattern" is also known as the "observer pattern" and is a pretty widely pervasive software design pattern.

Just because I cannot leave it, as it is ;): Thats not completely true. In the Subject-Observer-Pattern the observers are directly connected to their subject (=> the oberservers knows about their concrete subject (=> no observer, if there is no subject to observe)) and they only get notified, that "something" happened, but usually without any further information. Within the Event-Pattern it's even not required, that the listeners have _any_ connection to a subject. They are connected to a generalized handler and one, or more subjects can trigger an event without letting the handler know, who they are (it's in fact not even required, that a subject exists). Usually the event is quite arbitrary, especially it can carry arbitrary payload. Of course that always depends on the concrete implementation and may differ ;) 

Beside this there is a different semantic, because one observes something (concrete) and the other just waits for an event :)

Just said

--
github.com/KingCrunch

[Patrick Mulvey]

On Wednesday, October 10, 2012 11:37:16 AM UTC+1, Matthew Lanigan wrote:

I think you misunderstood me. I'm not contesting that people are using event patterns. I was asking how you define an event pattern. How do you distinguish between an event pattern and a non-event pattern? Does an event pattern have to use a defined Event or EventDispatcher class?

The "event pattern" is also known as the "observer pattern" and is a pretty widely pervasive software design pattern.

It is called a "pattern" because it is just that -- an underlying design pattern; it is not the names of the classes involved, or even the interface through which they're accessed (similar to how a pattern is used to cut out the cloth for a piece of clothing -- but doesn't define the cloth or embellishments).

I'm not really sure that the problem you are professing is a problem at all.

Don't get me wrong, I'm not saying that the event pattern isn't a pattern. I'm just asking if there's a formal definition of this pattern somewhere that we are going to use, because it isn't a pattern natively built into PHP. 

 

Regardless, I agree with the sentiment that an "@event" tag should not be included in the core PHPDoc PSR, but should rather be defined as a PHPDoc extension in a future Event-related PSR -- and this standard of "core" vs. "extension" should also be applied to any non-standard, implementation-related PHPDoc tags in the future.

By leaving open the opportunity for extension by future PSRs, the PHPDoc standard, essentially, gains a level future-proofing that is not insubstantial, and it also allows those extensions to occur without unnecessary bloating of the core PHPDoc PSR.

Totally agree with this. The core spec should define tags that are "common" - i.e. metadata such as @author, or things that are part of PHP like @return. It should also be specifically open to extension by future PSRs, perhaps within some broad syntax limits (such as using the @ symbol for new tags, etc.). 

I would definitely be in favor of excluding @event from the core spec and delegating it to an extension to be defined later. 

[Ryan Parman]

So, again...

On Oct 9, 2012, at 11:46 PM, Ryan Parman <ry...@ryanparman.com> wrote:

> I'm genuinely interested in learning about what other event systems are actually seeing real-world use. Even if @event doesn't make it into the formal PHPDoc PSR (as I'd prefer), understanding (a) what else is out there, and (b) how to define a spec that fits them is -- I think -- important.

If the consensus is that we don't add @event to the core PHPDoc spec, then how to we move forward? A couple of people have mentioned "future extension" or something similar. What does that look like?

I am presently working on tag support for my own documentation generator. I also am involved in another project that makes heavy use of the observer pattern (events). My work is -- quite literally -- blocked.

I'm hoping to work with the community to find a solution for documenting events that we can all share. So far, my suggestion has been shot down. All right. So, what does an alternative look like -- practically speaking?

[Ryan Parman]

I just came across this:

https://github.com/phpDocumentor/phpDocumentor2/blob/develop/docs/PSR.md#531-tag-name

...which suggests that custom tags are allowed provided that they are prepended with a vendor prefix.

So, if I'm using ApiGen as my documentation tool, but I want to note that I'm using Symfony EventDispatcher events, which way would I go?

/**
* @apigen-event [...syntax and description...]
*/

or...

/**
* @symfony-event [...syntax and description...]
*/

Does either vendor have a preference?

[Sebastian Krebs]

2012/10/10 Ryan Parman <ry...@ryanparman.com>

I would say "ryan-" or something like that, because you are neither the vendor of symfony, nor of apigen and both also doesn't define such a tag on it's own. Claiming a vendor-prefix of a foreign vendor is not nice ;)

 

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To post to this group, send email to php...@googlegroups.com.
To unsubscribe from this group, send email to php-fig+u...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

--
github.com/KingCrunch

[Ryan Parman]

On Oct 10, 2012, at 11:55 AM, Sebastian Krebs <kreb...@gmail.com> wrote:

2012/10/10 Ryan Parman <ry...@ryanparman.com>

So, if I'm using ApiGen as my documentation tool, but I want to note that I'm using Symfony EventDispatcher events, which way would I go?

    /**
     * @apigen-event [...syntax and description...]
     */

or...

    /**
     * @symfony-event [...syntax and description...]
     */

Does either vendor have a preference?

I would say "ryan-" or something like that, because you are neither the vendor of symfony, nor of apigen and both also doesn't define such a tag on it's own. Claiming a vendor-prefix of a foreign vendor is not nice ;)

Let me rephrase and provide some context:

I am the author of a tool called Vanity that is a competing product to phpDocumentor (neé DocBlox), ApiGen and Sami. I intend to add support for a syntax that enables developers to document their events, and have Vanity understand them.

Is it more appropriate to say:

"I am a documentation tool. Give me all of your events." (e.g., @vanity-event, @apigen-event, @phpdocumentor-event)

or...

"Give me the events provided by a particular event library, and I will document them." (e.g., @symfony-event, @zf2-event)

?

[Sebastian Krebs]

2012/10/10 Ryan Parman <ry...@ryanparman.com>

As far as I can see that doesn't change anything. A vendor-prefixed-something always defines a "something" introduced and defined by a specific vendor to avoid conflicts with other "somethings" from other vendors. You will face several problems the moment, when (e.g.) symfony decides to introduce their own (probably incompatible) definition of @symfony-event. Beside that it will probably confuse others, that a tag @symfony-event exists, that isn't defined by symfony, but by any third party tool. Question regarding this tag will probably going to the symfony-mailinglist first and all they can say is "It's not from here, look something else".

And even more beside that: Feels not clean to me to introduce an arbitrary number of (dynamic ...) tags, that all say the same and only differs in a single attribute (the vendor).

I must say, that I don't completely get, how we come to this discussion right now ;) But I hope that your tool is not the (only) reason why you want @event into a PSR. Your tool can support whatever you want. No need for an overlaying standard ;)

Regards,

Sebastian

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To post to this group, send email to php...@googlegroups.com.
To unsubscribe from this group, send email to php-fig+u...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

--
github.com/KingCrunch

[Ryan Parman]

On Oct 10, 2012, at 1:40 PM, Sebastian Krebs <kreb...@gmail.com> wrote:

> I must say, that I don't completely get, how we come to this discussion right now ;) But I hope that your tool is not the (only) reason why you want @event into a PSR. Your tool can support whatever you want. No need for an overlaying standard ;)

My goals are simple:

1. Developers are using events in PHP.
2. Developers need a way to *effectively* document events.
3. Users need to be able to understand *how* to leverage the events.

My first attempt was to propose an enhancement to the pending PSR document. When that was rejected, I wanted to find out what alternatives were available.

By digging more deeply into Mike's PSR draft, I found that he was suggesting that (a) all custom tags should be vendor-prefixed, and (b) any non-prefixed tags should be part of the spec. This means that implementing my own support for "@event" is invalid and non-compliant. This brought me to my next set of questions: Should the vendor be me, or should it represent the kind of event that we're supporting. Based on the conversation, it sounds as though the appropriate approach is to use @vanity-event.

Using @vanity-event as a tag means a few things:

1. Developers will now be able to adequately describe the events that are triggered by a method.

2. Users/consumers will be able to more easily understand the events that are triggered by a method.

3. @vanity-event, as a vendor-prefixed tag, exists inside the confines of the specification and should be both backwards and forwards-compatible with said spec.

4. Developers who choose to leverage this extension will now have to deal with vendor lock-in, making it more difficult for them to switch documentation tools in the future.

But, it is what it is. I agree that prematurely defining a specification around inconsistent event interfaces is bad, but I'm disappointed that nobody else seemed to be interested in finding ways to move this forward without modifying the core spec. I've been left to go off and implement something independently without much input on how to make something like this succeed.

I'm going to go ahead and put together a standalone specification to document how such a tag should be interpreted when added to a DocComment. Feedback from the group is welcome, and I will -- at some point -- put it to a vote.

[Patrick Mulvey]

I can understand your frustration. But forming a consensus in a group like this where there will always be differences of opinion is going to take a while. Unfortunately that may hinder your own development timetable.

Reading this thread, I've become convinced that:

• If the spec tries to cover everything, it means adding in @event, @log, @emails, and all kinds of other tags
• Trying to add those tags would require a huge amount of discussion, because the tag syntax would have implications for the implementation of those features (or vice versa)
• Therefore, the spec should define "core" features (things that there are standard implementations for, native PHP features, and metadata)
• To allow things like @event, @log etc. to be included, the spec must be open for future extension

If the consensus is that we don't add @event to the core PHPDoc spec, then how to we move forward? A couple of people have mentioned "future extension" or something similar. What does that look like? 

Well, the core spec would define a general syntax for tags, and a list of the "core" tags. It would explicitly state that future PSRs may add new tags, preferably with links to those PSRs added as they are approved.

At some point in the future, an Events PSR is proposed. There's a discussion, and eventually a some standard for implementing an event pattern in PHP is agreed upon. Once the pattern has been decided, it should be fairly trivial to add a description of the tag structure(s) to use for documenting events. This tag structure would be included in the Events PSR, linking back to the core documentation PSR. 

I believe this is the best model for us to adopt. The only major downside is that for now, event tags won't have any standard syntax. But ultimately, you can't define how event documentation should work until you define how events should work. And that's a bigger discussion than what we've had in this thread so far.

In the meantime, your problem is figuring out how to support documenting events in your own Vanity documentation tool. I think the vendor-prefix thing is a bit of a red herring - I believe the intent is that vendors of code using events (e.g. people like Symfony) can use vendor prefixes (such as symfony-event). I don't think it was intended to mean that documentation tools would be the ones adding a prefix. You are not a vendor - you're a documentation tool. 

Based on the conversation, it sounds as though the appropriate approach is to use @vanity-event.

I thoroughly disagree with this reasoning.

I think the correct approach is for you to support any prefixed event tag. You could look for @vendor-event tags, where the "vendor" part is variable. You could then have a generic implementation for generating the documentation, or define it on a vendor-by-vendor basis as it is adopted. This would allow any vendor to document events using prefixed tags (Symfony can start using @symfony-event, Annovent can use @annovent-event, etc.) under your system, without you trying to enforce something like @vanity-event to all vendors.

Is it more appropriate to say:

"I am a documentation tool. Give me all of your events." (e.g., @vanity-event, @apigen-event, @phpdocumentor-event)

or...

"Give me the events provided by a particular event library, and I will document them." (e.g., @symfony-event, @zf2-event)

The second option is obviously more appropriate - the documentation tool should serve the code author, not the other way around. The first option should not even exist. My suggestion above should allow you to support this, and now vendors and users can document their events without tying themselves into any one documentation tool (because, for example, ApiGen can always add in their own support for @symfony-event).

Of course, if a standard @event tag is created at some point in the future, vendors might have to do a bit of painful switching from @vendor-event to @event, but at this stage I think that's an unavoidable reality. 

[Paul Jones]

On Oct 10, 2012, at 6:32 PM, Patrick Mulvey wrote:

> I think the correct approach is for you to support any prefixed event tag. You could look for @vendor-event tags, where the "vendor" part is variable. You could then have a generic implementation for generating the documentation, or define it on a vendor-by-vendor basis as it is adopted. This would allow any vendor to document events using prefixed tags (Symfony can start using @symfony-event, Annovent can use @annovent-event, etc.) under your system, without you trying to enforce something like @vanity-event to all vendors.
>
> Is it more appropriate to say:
>
> "I am a documentation tool. Give me all of your events." (e.g., @vanity-event, @apigen-event, @phpdocumentor-event)
>
> or...
>
> "Give me the events provided by a particular event library, and I will document them." (e.g., @symfony-event, @zf2-event)
>
> The second option is obviously more appropriate - the documentation tool should serve the code author, not the other way around. The first option should not even exist. My suggestion above should allow you to support this, and now vendors and users can document their events without tying themselves into any one documentation tool (because, for example, ApiGen can always add in their own support for @symfony-event).

I agree with this sentiment. The events (or notifications, or signals) being sent would need to be documented according to the event (or notification, or signal) implementation being used by the code under documentation. The various vendors of those systems might publish their PHPDoc standards for their particular implementations.


-- pmj

[Mike van Riel]

I agree as well.

The prefix was introduced to add a form of namespacing so that
libraries using tags
would not create duplicate tags and thus tags where a large consensus
exists should
be prefix-less.

Patrick hit the nail on the head where he stated that for a broad
support of eventing
a new PSR should be created that can define a common interoperability PSR that
could contain tags/annotations. This is what I meant with extending the Core
specification; new tags _will_ get invented but might be specific for
a use-case and as
such do not fit the core spec.

The goal of a Documentation Generator is to support the code author at
all times and
may even support things not in the spec. (For example: phpDocumentor2
has support
for PHPUnit @covers annotation; which is explicitly omitted from the spec)

[Chuck Burgess]

I reckon I need some clarification, not being familiar with this event usage in the code...

Does @event simply document the code, or does the @event tag itself actually affect the runtime behavior of the code?

If it's the latter, that falls into the realm of annotations, doesn't it?

If it's the former, can't @see provide the info that you want the reader to see, as well as the link to the code element that you want to point to?

[Ryan Parman]

I'm choosing to move forward with this. Here is a proposed spec for @event/@events that I intend to implement support for.

https://github.com/skyzyx/vanity/wiki/PHPDoc-Extension:-@event%28s%29

Since the spec is about how @event/@events is intended to be interpreted, feedback is both welcome and appreciated from anyone who wants to help shape this document.

[Mike van Riel]

Your enthusiasm is commendable!

I would like to help you by providing a little extra information to
make sure well informed design is chosen.
Event-driven development comes in many shapes and size, there are
several design patterns to be aware of.

Luckily Elizabeth Marie Smith (aureasrose) has held a presentation on
this subject at #DPC12 (http://joind.in/talk/view/6249); I can
recommend reading the slides that she used as they provide a lot of
information regarding the design of event driven development. Another
interesting implementation to observe may be that of YUI
(http://yuilibrary.com/yui/docs/event/) and to investigate what Flow3
offers, given that they make heavy use of annotations.

Right, so far theory, regarding your tag signature: I would like to
ask you how you intend to distinguish between the type, identifier and
description field?
Am I correct to interpret that you intend to separate the text
following the tag into 3 sections based on spaces and if the first
contains a dot that that is an event?
This does 'force' your user to adopt the dot separator and have
multiple parts; is that desirable?

Specifically the separation between type and identifier can be trouble
some if the type is not recognized by the documentation generator.

Example:

@event string string this fires a string

@event string this fires a string

Regardless of the sillyness of such event I hope I can clarify that
the parse has no way of recognizing which pattern is used if type if
not a required part of the signature.

Also, what is the added value of having two tags, event and events.
Why would the user just have multiple @event entries; or an @event
entry with multiple event names?
Providing two tags may lead to confusion which to use (see @throw and
@throws; do you know which one is right?)

Finally, it would be so supercool if this could be picked up in a
wider sense; to have a full-fledged PSR for EventDispatchers/Managers,
etc in the PHP ecosphere.

[Patrick Mulvey]

Nice work putting together a written proposal. That makes discussion a lot easier.

Coupla questions/comments:

1) When you say you're "moving forward with this" - does that mean you're going to actually implement this, or you're moving forward by proposing this extension? Are you going to ask for feedback and votes on this proposal before it is used?

2) I agree with Mike - why use @event and @events instead of just @event? IMO adding in the plural version is confusing (and it's also easy to mis-read @events as @event). Multiple @event tags would be preferable to an @events tag.

3) Have you considered moving forward by supporting vendor prefixed (@vendor-event) tags as discussed above? An alternative might be @beta-event. Personally I would prefer this over @event, since there hasn't really been a discussion in this group about events themselves. It would be nice to keep @event open until that occurs. Using vendor- or beta- prefixed tags would still allow you to meet the three goals you set out in this document, but would have the advantage of not introducing potential forward-compatibility issues if an alternative @event tag syntax is proposed in the future. 

4) What do you think of the idea of calling this tag @dispatches (or @fires or @triggers or something similar) instead of @event? This feels cleaner to me, as it describes what the code actually does (in the same way that @throws describes that an exception may be thrown, @dispatches could describe that an event may be dispatched.

5) Have you thought about using extra tags to allow more granular documentation of when events are fired? For example, I may have a method that immediately fires an event when it is called, and fires a second event only when the method has completed some task successfully (similar to the example code you give in this document). For this, I may want to use something like @preEvent to document the first event (which is fired every time the method is called) and @postEvent (which is conditionally fired at the end of the method body). However this may be adding too much detail. 

[Niels Braczek]

Am 11.10.2012 19:05, schrieb Ryan Parman:

> Since the spec is about how @event/@events is intended to be interpreted, feedback is both welcome and appreciated from anyone who wants to help shape this document.

Another use case:
Joomla! uses events to allow plugins to hook in by providing a method
with the name of the event, fx. onContentAfterSave:

public function onContentAfterSave($context, &$article, $isNew)
{
...
}

Extensions may introduce their own events. Events can be triggered
nearly everywhere using a global dispatcher (kind of signal slot). Since
an event is identified by a string, which sometimes get constructed at
runtime, it is quite hard (nearly impossible) to find all the places,
where a specific event is fired. So a practical need is to document all
the events, that can be triggered within a specific method. For this
purpose, the following syntax would be helpful:

/**
* Sample Method
* ...
* @events onContentBeforeSave, onContentAfterSave,
* onContentBeforeDelete, onContentAfterDelete
*/
public function anyMethod()
{
...
$dispatcher->trigger($event, $args);
...
}

The rule "The event identifier MUST be composed of two or more segments
which are period-delimited" would render the @event(s) tag useless for
this use case.

So I suggest not to restrict the format of the event identifier.

Regards,
Niels

--
| http://barcamp-wk.de · 2. Barcamp Westküste Frühjahr 2013 |
| http://www.bsds.de · BSDS Braczek Software- und DatenSysteme |
| Webdesign · Webhosting · e-Commerce · Joomla! Content Management |
------------------------------------------------------------------

[Ryan Parman]

On Oct 11, 2012, at 10:42 AM, Mike van Riel <draco...@gmail.com> wrote:

> Luckily Elizabeth Marie Smith (aureasrose) has held a presentation on
> this subject at #DPC12 (http://joind.in/talk/view/6249); I can
> recommend reading the slides that she used as they provide a lot of
> information regarding the design of event driven development. Another
> interesting implementation to observe may be that of YUI
> (http://yuilibrary.com/yui/docs/event/) and to investigate what Flow3
> offers, given that they make heavy use of annotations.

I will certainly take a look at these. Thank you.

> Right, so far theory, regarding your tag signature: I would like to
> ask you how you intend to distinguish between the type, identifier and
> description field?
> Am I correct to interpret that you intend to separate the text
> following the tag into 3 sections based on spaces and if the first
> contains a dot that that is an event?
> This does 'force' your user to adopt the dot separator and have
> multiple parts; is that desirable?

Your assessment is correct. I'm not necessarily locked into this, but I needed to start somewhere.

I know that MY projects use periods in event names, and I've seen other projects do the same, but admittedly my research hasn't had a particularly broad scope so far.

> Specifically the separation between type and identifier can be trouble
> some if the type is not recognized by the documentation generator.
>
> Example:
>
> @event string string this fires a string
>
> @event string this fires a string
>
> Regardless of the sillyness of such event I hope I can clarify that
> the parse has no way of recognizing which pattern is used if type if
> not a required part of the signature.

Agreed. This is why the proposal clearly articulates that event identifiers contain at least one period. I do recognize that this may be an ill-advised limitation, and am open to alternative suggestions.

> Also, what is the added value of having two tags, event and events.
> Why would the user just have multiple @event entries; or an @event
> entry with multiple event names?
> Providing two tags may lead to confusion which to use (see @throw and
> @throws; do you know which one is right?)

I agree with you 100%, and I will certainly be using @event in my own projects (the proposal states that this is the preferred approach), but I'm also attempting to account for existing uses of @event in the wild.

For example, Zend Framework 2 uses @events (plural) -- in the way the proposal describes -- in their MVC classes.

> Finally, it would be so supercool if this could be picked up in a
> wider sense; to have a full-fledged PSR for EventDispatchers/Managers,
> etc in the PHP ecosphere.

I would love to see this happen. I think it would be a very positive move forward.

[Ryan Parman]

On Oct 11, 2012, at 11:27 AM, Patrick Mulvey <pdmu...@gmail.com> wrote:

1) When you say you're "moving forward with this" - does that mean you're going to actually implement this, or you're moving forward by proposing this extension? Are you going to ask for feedback and votes on this proposal before it is used?

In an ideal world, I would wait for more discussion first.

But in reality, I have a project that leverages event dispatching heavily, and I need to be able to document those events for my end-users. I have a very practical, immediate need, and I don't have the time to wait for a potentially lengthy discussion and a vote.

So, I'm pulling a WebKit — that is to say, I'm implementing support for the proposal now and submitting it to the standards body at the same time. I expect the implementation to adjust and change a bit as more discussion occurs, but that's a bullet I'm going to have to bite.

2) I agree with Mike - why use @event and @events instead of just @event? IMO adding in the plural version is confusing (and it's also easy to mis-read @events as @event). Multiple @event tags would be preferable to an @events tag.

Yep, I agree. But ZF2 is using @events, and I wanted to attempt to accurately capture what was already happening in the wild.

3) Have you considered moving forward by supporting vendor prefixed (@vendor-event) tags as discussed above? An alternative might be @beta-event. Personally I would prefer this over @event, since there hasn't really been a discussion in this group about events themselves. It would be nice to keep @event open until that occurs. Using vendor- or beta- prefixed tags would still allow you to meet the three goals you set out in this document, but would have the advantage of not introducing potential forward-compatibility issues if an alternative @event tag syntax is proposed in the future.

I'm currently on the fence about this one.

Web browsers presently use -webkit, -moz, -ms and -o as CSS prefixes, with a default being non-prefixed. Over time as the spec shapes up, a browser will add support for the non-prefixed version while typically continuing to support the prefixed version.

Both considering as well as discarding the language in the current draft of Mike's PHPDoc spec, I've considered:

@event

@:event

@-event

@vanity-event

@v-event

@-vanity-event

@-v-event

@:vanity-event

@:v-event

I'm trying to find one that implies that it isn't part of the core spec, and it might change over time. At the moment, I was going to implement support for both @event and @vanity-event (as well as their pluralized counterparts), but I haven't written any code yet.

Thoughts?

4) What do you think of the idea of calling this tag @dispatches (or @fires or @triggers or something similar) instead of @event? This feels cleaner to me, as it describes what the code actually does (in the same way that @throws describes that an exception may be thrown, @dispatches could describe that an event may be dispatched.

I'd not considered that, but it's not a bad idea. The only issue I see is that I've not found a single instance of @dispatches in the wild, but I've seen @event on multiple occasions. Using @event seemed like the most pragmatic way forward.

5) Have you thought about using extra tags to allow more granular documentation of when events are fired? For example, I may have a method that immediately fires an event when it is called, and fires a second event only when the method has completed some task successfully (similar to the example code you give in this document). For this, I may want to use something like @preEvent to document the first event (which is fired every time the method is called) and @postEvent (which is conditionally fired at the end of the method body). However this may be adding too much detail.

I hadn't considered that — mostly because my own usage places that information in the event identifier instead (e.g., vendor.task.pre, vendor.task.post).

[Ryan Parman]

On Oct 11, 2012, at 2:18 PM, Niels Braczek <nbra...@bsds.de> wrote:

> The rule "The event identifier MUST be composed of two or more segments
> which are period-delimited" would render the @event(s) tag useless for
> this use case.
>
> So I suggest not to restrict the format of the event identifier.

Good point. I had not seen events used like the before, but it makes sense to me. This pattern is used in JavaScript all the time.

So, the constraint is that we're trying to support:

* Typed and untyped event systems (therefore, <Type> is optional).
* A way to identify the event.
* An optional description.

How might you suggest changing the format in a way that doesn't limit Joomla!, but the tokens can still be parsed correctly?

[Patrick Mulvey]

On Friday, October 12, 2012 8:04:56 AM UTC+1, Ryan Parman wrote:

On Oct 11, 2012, at 11:27 AM, Patrick Mulvey <pdmu...@gmail.com> wrote:

1) When you say you're "moving forward with this" - does that mean you're going to actually implement this, or you're moving forward by proposing this extension? Are you going to ask for feedback and votes on this proposal before it is used?

In an ideal world, I would wait for more discussion first.

But in reality, I have a project that leverages event dispatching heavily, and I need to be able to document those events for my end-users. I have a very practical, immediate need, and I don't have the time to wait for a potentially lengthy discussion and a vote.

So, I'm pulling a WebKit — that is to say, I'm implementing support for the proposal now and submitting it to the standards body at the same time. I expect the implementation to adjust and change a bit as more discussion occurs, but that's a bullet I'm going to have to bite.

I'll be honest - I think this is a bad idea. If you publish a tool that makes use of @event, and it starts getting used as an unofficial standard, it will create conflicts later if this group (or anyone else, really) puts together a different standard for @event. If that happens, it won't just be you who is inconvenienced by it. This has the potential to affect a lot of developers. 

Section 5.3 of the PHPDoc proposal (which you've linked to several times) specifically states "Tag names that are not prefixed with a vendor or namespace MUST be described in this specification (see chapter 7) and/or any official addendum.". If you're going forward with @event without waiting for a discussion and votes first, then you're clearly going against this clause. 

As Mike and Niels have pointed out, there some issues with your proposed syntax. This is mainly because there hasn't been enough discussion yet. I understand you want to get on with documenting events immediately, without waiting for a protracted discussion. But there are ways of doing this (see below) that don't introduce the potential for compatibility problems in the future. 

As mentioned earlier, you can document events simply by using vendor-prefixing. 

 

2) I agree with Mike - why use @event and @events instead of just @event? IMO adding in the plural version is confusing (and it's also easy to mis-read @events as @event). Multiple @event tags would be preferable to an @events tag.

Yep, I agree. But ZF2 is using @events, and I wanted to attempt to accurately capture what was already happening in the wild.

The reason for these differences in the wild is that there is no defined standard - vendors have been making it up as they go. If a clear, sensible standard was accepted and became the norm, I imagine that vendors would eventually switch to use it. Having both @event and @events is obviously confusing and I don't think it should be standardised. 

 

3) Have you considered moving forward by supporting vendor prefixed (@vendor-event) tags as discussed above? An alternative might be @beta-event. Personally I would prefer this over @event, since there hasn't really been a discussion in this group about events themselves. It would be nice to keep @event open until that occurs. Using vendor- or beta- prefixed tags would still allow you to meet the three goals you set out in this document, but would have the advantage of not introducing potential forward-compatibility issues if an alternative @event tag syntax is proposed in the future.

I'm currently on the fence about this one.

Web browsers presently use -webkit, -moz, -ms and -o as CSS prefixes, with a default being non-prefixed. Over time as the spec shapes up, a browser will add support for the non-prefixed version while typically continuing to support the prefixed version.

Both considering as well as discarding the language in the current draft of Mike's PHPDoc spec, I've considered:

@event

@:event

@-event

@vanity-event

@v-event

@-vanity-event

@-v-event

@:vanity-event

@:v-event

I'm trying to find one that implies that it isn't part of the core spec, and it might change over time. At the moment, I was going to implement support for both @event and @vanity-event (as well as their pluralized counterparts), but I haven't written any code yet.

Thoughts?

As I described earlier in this thread, I don't think @vanity-event is appropriate at all. You know I think @event is a bad idea. I would propose supporting @vendor-event (so each vendor can use their own prefix) or @beta-event because it makes it clear that it's not an accepted standard yet, and is subject to modification. @beta-event may be the most clear way to indicate this.

Using a prefixed version allows you to start documenting events immediately without the issues of using @event itself. So then everybody's happy, right?

 

4) What do you think of the idea of calling this tag @dispatches (or @fires or @triggers or something similar) instead of @event? This feels cleaner to me, as it describes what the code actually does (in the same way that @throws describes that an exception may be thrown, @dispatches could describe that an event may be dispatched.

I'd not considered that, but it's not a bad idea. The only issue I see is that I've not found a single instance of @dispatches in the wild, but I've seen @event on multiple occasions. Using @event seemed like the most pragmatic way forward.

That's true. I'd argue that if @dispatches became available in documentation tools it would be adopted. Perhaps both could be supported.

 

5) Have you thought about using extra tags to allow more granular documentation of when events are fired? For example, I may have a method that immediately fires an event when it is called, and fires a second event only when the method has completed some task successfully (similar to the example code you give in this document). For this, I may want to use something like @preEvent to document the first event (which is fired every time the method is called) and @postEvent (which is conditionally fired at the end of the method body). However this may be adding too much detail.

I hadn't considered that — mostly because my own usage places that information in the event identifier instead (e.g., vendor.task.pre, vendor.task.post).

Now that you have considered it, what are your thoughts?

[Niels Braczek]

Am 12.10.2012 09:08, schrieb Ryan Parman:

> So, the constraint is that we're trying to support:
>
> * Typed and untyped event systems (therefore, <Type> is optional).
> * A way to identify the event.
> * An optional description.
>
> How might you suggest changing the format in a way that doesn't limit Joomla!, but the tokens can still be parsed correctly?

The overall format is ok for our needs, as long as eg.
'onBeforeContentSave' is a valid event identifier.

If you just delete 2.1 and 2.2 from the description, the new tags would
work perfectly for us.

[Ryan Parman]

On Oct 12, 2012, at 5:12 AM, Niels Braczek <nbra...@bsds.de> wrote:

> The overall format is ok for our needs, as long as eg.
> 'onBeforeContentSave' is a valid event identifier.
>
> If you just delete 2.1 and 2.2 from the description, the new tags would
> work perfectly for us.

I understand that it makes sense from a usage perspective. However, this doesn't resolve how documentation tools would parse this.

What if we proposed to use angle brackets around the optional type? Or, piggybacking on an idea brought-up in the @alias thread, wrapping it in colons (i.e., :type:).

Thoughts?

[Drak]

Would it help to use braces with this particular tag?  (as was suggested with @author?)

Drak

[Ryan Parman]

On Oct 12, 2012, at 2:45 AM, Patrick Mulvey <pdmu...@gmail.com> wrote:

[…] I'll be honest - I think this is a bad idea. If you publish a tool that makes use of @event, and it starts getting used as an unofficial standard, it will create conflicts later if this group (or anyone else, really) puts together a different standard for @event. If that happens, it won't just be you who is inconvenienced by it. This has the potential to affect a lot of developers.

Valid point.

Section 5.3 of the PHPDoc proposal (which you've linked to several times) specifically states "Tag names that are not prefixed with a vendor or namespace MUST be described in this specification (see chapter 7) and/or any official addendum.". If you're going forward with @event without waiting for a discussion and votes first, then you're clearly going against this clause.

I understand. I was weighing the pros and cons of following that section and supporting `@event`. I hadn't made up my mind yet, and I hadn't written any code yet.

As Mike and Niels have pointed out, there some issues with your proposed syntax. This is mainly because there hasn't been enough discussion yet. I understand you want to get on with documenting events immediately, without waiting for a protracted discussion. But there are ways of doing this (see below) that don't introduce the potential for compatibility problems in the future. 

As mentioned earlier, you can document events simply by using vendor-prefixing.

I think you're right. But there was also some debate about what that vendor prefix should be.

Even then, the proposal should still be called "@event", but implementations should remain vendor-prefixed until such a PSR is ratified.

[…] The reason for these differences in the wild is that there is no defined standard - vendors have been making it up as they go. If a clear, sensible standard was accepted and became the norm, I imagine that vendors would eventually switch to use it. Having both @event and @events is obviously confusing and I don't think it should be standardised.

I'm fine with that. I had no intention of using @events myself, but I'm also trying to feel-out how pragmatic of an approach the proposal should take here. This is new territory.

[…] As I described earlier in this thread, I don't think @vanity-event is appropriate at all. You know I think @event is a bad idea. I would propose supporting @vendor-event (so each vendor can use their own prefix) or @beta-event because it makes it clear that it's not an accepted standard yet, and is subject to modification. @beta-event may be the most clear way to indicate this.

Using a prefixed version allows you to start documenting events immediately without the issues of using @event itself. So then everybody's happy, right?

Sure, but I'm a little confused. @event is the tag, "vanity" is MY vendor prefix. Using the names of Event Dispatching software is problematic because we're trying to produce a single standard, not a splintered one (e.g., symfony-event, @zf2-event). @beta-event is... okay... but it just doesn't quite feel right to me, although I can't pinpoint why.

[…] That's true. I'd argue that if @dispatches became available in documentation tools it would be adopted. Perhaps both could be supported.

I'm not opposed to that. Again, I'm trying to feel-out the proper level of pragmatism here.

 

5) Have you thought about using extra tags to allow more granular documentation of when events are fired? For example, I may have a method that immediately fires an event when it is called, and fires a second event only when the method has completed some task successfully (similar to the example code you give in this document). For this, I may want to use something like @preEvent to document the first event (which is fired every time the method is called) and @postEvent (which is conditionally fired at the end of the method body). However this may be adding too much detail.

I hadn't considered that — mostly because my own usage places that information in the event identifier instead (e.g., vendor.task.pre, vendor.task.post).

Now that you have considered it, what are your thoughts?

I think that *when* the events fire is entirely up to the software, and is probably too granular for the DocBlock. In my own uses cases, I frequently fire multiple pre/post events in a given task. As such, I feel like @preEvent and @postEvent are arguably a bit too niche at present.

[Ryan Parman]

On Oct 12, 2012, at 11:29 AM, Drak <dr...@zikula.org> wrote:

Would it help to use braces with this particular tag?  (as was suggested with @author?)

What would it look like?

[Sebastian Krebs]

Just curious: Is this still about something related to this mailinglist (meaning: Something related to FIG/PSR), or are you discussing the implementation of your tool? Because I guess this is going offtopic

Regards,

Sebastian

2012/10/12 Ryan Parman <ry...@ryanparman.com>

On Oct 12, 2012, at 11:29 AM, Drak <dr...@zikula.org> wrote:

Would it help to use braces with this particular tag?  (as was suggested with @author?)

What would it look like?

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To post to this group, send email to php...@googlegroups.com.
To unsubscribe from this group, send email to php-fig+u...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

--
github.com/KingCrunch

[Ryan Parman]

Minor updates to address some of the initial feedback:

* Removed @events.
* Removed the constraint of requiring a period in the event name.
* Added a requirement that if a type is listed (optional), it must be wrapped in angle brackets (a la @author).

https://github.com/skyzyx/vanity/wiki/PHPDoc-Extension:-@event

[Ryan Parman]

On Oct 12, 2012, at 1:18 PM, Sebastian Krebs <kreb...@gmail.com> wrote:

> Just curious: Is this still about something related to this mailinglist (meaning: Something related to FIG/PSR), or are you discussing the implementation of your tool? Because I guess this is going offtopic

This is directly related to FIG/PSR.

How/when I implement support for it is unrelated to this discussion.

[Niels Braczek]

@events was a practical shortcut, but I could live without it.

Beside of that, the current proposal is suitable for us.

[Patrick Mulvey]

I had a read through your updated proposal. I think it's a lot better (generally more robust) than the first version.

On Friday, October 12, 2012 7:40:27 PM UTC+1, Ryan Parman wrote:

Section 5.3 of the PHPDoc proposal (which you've linked to several times) specifically states "Tag names that are not prefixed with a vendor or namespace MUST be described in this specification (see chapter 7) and/or any official addendum.". If you're going forward with @event without waiting for a discussion and votes first, then you're clearly going against this clause.

I understand. I was weighing the pros and cons of following that section and supporting `@event`. I hadn't made up my mind yet, and I hadn't written any code yet.

 

Surely the biggest pro of following the spec is ensured compatibility with that standard and its official extensions (which I assume you want, as as documentation tool author).

As Mike and Niels have pointed out, there some issues with your proposed syntax. This is mainly because there hasn't been enough discussion yet. I understand you want to get on with documenting events immediately, without waiting for a protracted discussion. But there are ways of doing this (see below) that don't introduce the potential for compatibility problems in the future. 

As mentioned earlier, you can document events simply by using vendor-prefixing.

I think you're right. But there was also some debate about what that vendor prefix should be.

 

I proposed earlier in this thread that it shouldn't be @vanity-event, if vanity is the name of your documentation tool. There seemed to be some agreement on that point. 

Even then, the proposal should still be called "@event", but implementations should remain vendor-prefixed until such a PSR is ratified.

Agreed.

 

[…] As I described earlier in this thread, I don't think @vanity-event is appropriate at all. You know I think @event is a bad idea. I would propose supporting @vendor-event (so each vendor can use their own prefix) or @beta-event because it makes it clear that it's not an accepted standard yet, and is subject to modification. @beta-event may be the most clear way to indicate this.

Using a prefixed version allows you to start documenting events immediately without the issues of using @event itself. So then everybody's happy, right?

Sure, but I'm a little confused. @event is the tag, "vanity" is MY vendor prefix. Using the names of Event Dispatching software is problematic because we're trying to produce a single standard, not a splintered one (e.g., symfony-event, @zf2-event). @beta-event is... okay... but it just doesn't quite feel right to me, although I can't pinpoint why.

 

I'm not sure you count as a vendor as intended by the spec. If Vanity is a documentation tool, then I don't think the idea is for you to apply a prefix. I think it's for you to recognise other people's prefixes. My interpretation of "vendor" (yet another undefined term causing confusion) is that they're someone who produces code and wants to document it using tools such as Vanity. 

If you want to document Vanity itself, then @vanity-event would be used only for the internal documentation of Vanity. Other vendors would use their own prefixes in their own code. At least that's my interpretation.

@beta-event, while not covered by the PHPDoc proposal, is probably my favorite idea. It bypasses the confusion over who counts as a vendor, it provides a single name to be used by everyone, and it clearly indicates that the tag is experimental and subject to change. But supporting @symfony-event (etc.) is probably the way to go if you want to strictly follow the PHPDoc proposal.

5) Have you thought about using extra tags to allow more granular documentation of when events are fired? For example, I may have a method that immediately fires an event when it is called, and fires a second event only when the method has completed some task successfully (similar to the example code you give in this document). For this, I may want to use something like @preEvent to document the first event (which is fired every time the method is called) and @postEvent (which is conditionally fired at the end of the method body). However this may be adding too much detail.

I hadn't considered that — mostly because my own usage places that information in the event identifier instead (e.g., vendor.task.pre, vendor.task.post).

Now that you have considered it, what are your thoughts?

I think that *when* the events fire is entirely up to the software, and is probably too granular for the DocBlock. In my own uses cases, I frequently fire multiple pre/post events in a given task. As such, I feel like @preEvent and @postEvent are arguably a bit too niche at present.

Of course it's up to the software, but surely the point of documentation is to detail what the software does? My idea here was that users consuming code would be able to look at the documentation and not just see a list of events, but see events with additional context - e.g. this event fires when the method completes, this event fires if the method fails, etc. Perhaps this is another proposal in its own right though. Probably a bit off-topic for this conversation. 

[Andrew Eddie]

On Wednesday, 10 October 2012 07:38:44 UTC+11, Marc Bennewitz wrote:

Personally I don't like the name @event because the method triggering an
event itself isn't an event.
Like @throws describes en exception that may be throw.

A better name would be @triggers or @fires.

Agree, and I'd go with @triggers (verb).  My first impression was that @event (noun) was trying to document the listener or the observer method (this method IS the "event"), not that a method fired a particular event.

Regards,

Andrew Eddie

[Paul Jones]

Or maybe @sends.


-- pmj

[Niels Braczek]

Am 17.10.2012 22:10, schrieb Andrew Eddie:
> On Wednesday, 10 October 2012 07:38:44 UTC+11, Marc Bennewitz wrote:

>> A better name would be @triggers or @fires.

> Agree, and I'd go with @triggers (verb).

+1 for @triggers.

[Drak]

Surely, in keeping with the observer pattern, it should be @notifies. Event listeners are notified of the event, they are not triggered. The verb "to trigger", tells that something is triggered, like a detonator, which must then do something. An event listener simply listens passively and may decide do something: therefor, in line with the pattern's terminology, @notifies is much more appropriate. It also is more agnostic towards specific PHP implementations simply following the GOF pattern terminology.

Regards,

Drak

[Niels Braczek]

Am 18.10.2012 12:30, schrieb Drak:

> Surely, in keeping with the observer pattern, it should be @notifies. Event
> listeners are notified of the event, they are not triggered.

Given an listener (simplified layout)

class Listener
{
public function onFoo($args)
{
// ...
}

public function onBar($args)
{
// ...
}
}

and a class that wants to notify the listener

class Notifier
{
public function baz()
{
// ...
$this->notify('foo', $data);
// or
$dispatcher->trigger('foo', $data);
}
}

Said in plain English, Notifier::baz() notifies Listener about the event
foo.

If using @notifies, the documentation would either tell that foo is
notified (which obviously is wrong) or requiring to list any class with
an event handler without telling anything about the event itself (which
is absurd).

> The verb "to
> trigger", tells that something is triggered, like a detonator, which must
> then do something.

Yes. The event is triggered to be active.

> An event listener simply listens passively and may
> decide do something

Listeners are not of interest in this context. Events are.

> It also is more agnostic towards
> specific PHP implementations simply following the GOF pattern terminology.

The Observer-Subject pattern does not use event names, so this kind of
documentation is not needed there. GOF is not mentioning named events at
all, IIRC. Though, the tag we're talking about, is to be used to
document the places, where named events are triggered.

So @triggers is the right terminus.

[Drak]

On 18 October 2012 13:34, Niels Braczek <nbra...@bsds.de> wrote:

The Observer-Subject pattern does not use event names, so this kind of
documentation is not needed there. GOF is not mentioning named events at
all, IIRC. Though, the tag we're talking about, is to be used to
document the places, where named events are triggered.

So @triggers is the right terminus.

Event names are simply just groupings of events ad therefor just an optimisation of the GOF pattern.  Rather than having a separate dispatcher for each group it's all managed by one object split by names.

Even "dispatches" is better than triggers because trigger implies something is triggered to do something: but listeners are just that, they listen quietly and may do something.

With "dispatches" something is dispatched (communicated) to a destination - there is no implication that something must happen once it's reached there.

Regards,

Drak

[Mike van Riel]

And this is exactly why I am opposed to adopting an annotation without
defining the purpose of it and without having a complete PSR about
event management.
Event management comes in several variations (patterns) of which the
Observer pattern is just one, here is a small, non-exhaustive, list of
event management patterns with different domain models:

- Observer
- Event/Dispatcher
- Reactor
- PubSub
- Signal/Slot

Drak is talking about the Observer pattern, Niels and others may be
talking about Event/Dispatcher (used by Symfony2 for example), I have
heard someone mention Signal/Slot in here as well. Pick a pattern,
discuss a PSR to increase interoperability and then discuss naming an
annotation for it.
Without knowing what you are naming and what its purpose is it is not
possible to reach consensus.

[justin]

This++

On Thu, Oct 18, 2012 at 6:16 AM, Mike van Riel <draco...@gmail.com> wrote:
> And this is exactly why I am opposed to adopting an annotation without
> defining the purpose of it and without having a complete PSR about
> event management.
> Event management comes in several variations (patterns) of which the
> Observer pattern is just one, here is a small, non-exhaustive, list of
> event management patterns with different domain models:
>
> - Observer
> - Event/Dispatcher
> - Reactor
> - PubSub
> - Signal/Slot
>
> Drak is talking about the Observer pattern, Niels and others may be
> talking about Event/Dispatcher (used by Symfony2 for example), I have
> heard someone mention Signal/Slot in here as well. Pick a pattern,
> discuss a PSR to increase interoperability and then discuss naming an
> annotation for it.
> Without knowing what you are naming and what its purpose is it is not
> possible to reach consensus.

--
http://justinhileman.com

[Drak]

That's not what I said: These are all part of the same pattern, there are just variations on the same thing. Event/Dispatcher is very much the Observer with an optimisation as I already explained.

In the end, the same is true - listeners are notified of something happening which does not require they specifically do something. It's very much passive. Notification is passive. Triggering is not.

Drak

[Patrick Mulvey]

+1

[Niels Braczek]

Am 18.10.2012 16:49, schrieb Drak:

> In the end, the same is true - listeners are notified of something
> happening which does not require they specifically do something. It's very
> much passive. Notification is passive. Triggering is not.

It's not about listeners, it is about events.

The listeners are not known at development / documentation time, since
they are added at runtime. Thus, the *notification* of any specific
listener is not documentable/relevant. What needs documentation is the
event (or signal) that is *triggered*, so a developer / an IDE can see,
which events a listener can react on.

[Grzegorz Korba]

So what about using @triggers (like @throws) instead of @event? I see @Event "annotation" is used for example in \Symfony\Component\HttpKernel\KernelEvents for describing class related to event's name and I think it's better usage for it.

I'm sorry for digging it out since it's old thread, but I came here from google results and don't know if it's closed :-)

[Daniel Plainview]

Sorry, I didn't read whole thread, but I don't think it's fair to compare @throws and @triggers/@event/whatever.

@throws is a public contract supported by language. 

It's not about documentation in the first place.

IDE (PhpStorm) reports me if I missed catch block for non-RuntimeException.

My code may have a bug if I miss some checked exception.

@triggers is just some framework/implementation detail.

For example, I don't like Symfony's EventDispatcher for its eventName, eventClass separation,

it encourages to have generic FooEvent with several "event names" (aka event identifiers): "foo_was_boomed", "foo_was_doomed".

I prefer to have fine-grained events (each event has its own class): FooWasBoomed, FooWasDoomed.

Further, I like to make strict difference between events and hooks.

Events are "fire-and-forget", event listeners can be triggered synchronously, asynchronously (shutdown function or queues)

and I don't care about them. 

Hooks are special thing for involving 3rd parties into my flow, they are synchronous.

Symfony, on other hand, mixes these 2 concepts in 1.

Thus, I see here too many personal preferences,

so it makes me wonder what makes Symfony approach so special,

so it should have special annotation on PSR level?

[Grzegorz Korba]

I didn't want to say that Symfony's approach is special, only that I think the exact @Event notation is better for annotating event itself, not methods when events are triggered. For the latter one @triggers would be better in my opinion.

PS. I did not read whole thread and later I saw that @triggers was mentioned already. +1 for this one from me.

--
You received this message because you are subscribed to a topic in the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/php-fig/RdV06UsHD0o/unsubscribe.
To unsubscribe from this group and all its topics, send an email to php-fig+unsubscribe@googlegroups.com.

To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/741159e5-b5a4-41a2-b6be-951c631fd638%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

Pozdrawiam serdecznie
Grzegorz Korba

[Michael Cullum]

Hi folks,

Just a quick secretary reminder about self-throttling (two posts/topic/day & avoiding double posting) as this has gained 65 posts in 3 days and this makes topics extremely hard to follow and rather daunting.

On a technical note I'd add that we at phpBB use exactly this notation to document individual events, not the methods/functions that contain them. See https://github.com/phpbb/phpbb/blob/master/phpBB/common.php#L161 for an example.

We then compile these into documentation on the events in phpBB: https://wiki.phpbb.com/Event_List https://github.com/phpbb/phpbb/blob/master/phpBB/develop/export_events_for_wiki.php

Many thanks,

Michael

On Tuesday, 9 October 2012 07:09:04 UTC+1, Ryan Parman wrote:

I would like to propose the following enhancement to be included in a future PHPDoc-specific PSR: @event

@event

The @event tag is used to document events that are triggered by this function or method.

## Syntax

@event <"Type"> <"event_identifier"> [description]

## Description

With the @event tag, it is possible to document and event that is triggered by the function or method. When provided it MUST contain a "Type" (See Appendix A) to indicate what is returned; it MUST contain the name of the event that can be subscribed to by an event handler; the description on the other hand is OPTIONAL yet RECOMMENDED.

The @event tag MAY have a multi-line description and does not need explicit delimiting.

This tag MAY occur more than once in a "DocBlock" and is limited to the "DocBlock" of a type method or function.

## Examples

use Symfony\Component\EventDispatcher\Event;

use Vanity\Custom\Event\SimpleEvent;

/**

 * @event Event       vanity.task.all.complete Triggers when all of the tasks have been completed.

 * @event SimpleEvent vanity.task.failure      Triggers when a task fails to complete successfully.

 */