I am in the process of implementing an event dispatching system based in our application using the Symfony Event Dispatcher. A range of modules will be can be enabled or enabled by administrators and a central registry will automatically register the events that a plugin is interested in and handle the dispatching of events.
We currently use PHPDoc to generate all of our documentation and have a strict PHP Codesniffer standard that ensures documentation is complete and consistent.
What I want to do is automatically produce documentation that, in one place, lists all of the events which are available in the system; I want to make it easy to develop new plugins by making it easy to find out what events are available, what data is provided in these events and what responses can be sent with the events.
Is there any way to achieve this using PHPDoc? So far the best approach I have is to add a @uses tag to the method that notifies an event, referencing my PluginRegistry class; this way the related methods can at least be found, but it falls far short of ideal, as it provides no extra documentation (what event is available, what data, what return data or even how many events in the method).