Event Docblock Extractor/Parser

[mjauvin]

Extracts all the events doc blocks and returns the doc block comment and where it is triggered.

Example CMS page using this:

title = Events test
url = /events
layout = default
==  
use \Winter\Docs\Classes\EventParser;

function onInit()
{
    $this['coreEvents'] = EventParser::getPathEvents(base_path() . '/modules');
    $this['libraryEvents'] = EventParser::getPathEvents(base_path() . '/vendor/winter/storm/src', 'winter/storm/');
}
==
<section class="p-8">
    <a class="d-block" href="#core-events">Core Events</a>
    <a class="d-block" href="#library-events">Library Events</a>

    <h1 id="core-events" class="my-8">Core Events</h1>
    {% partial "events" items=coreEvents %}

    <h1 id="library-events" class="my-8">Library Events</h1>
    {% partial "events" items=libraryEvents %}
</section>

<style>
  pre {
      padding: 2rem;
      background: #eee;
  }
  blockquote {
      border-left: 5px solid blue;
      padding-left: 0.25rem;
  }
</style>

And the partial (events.htm):

{% for event in items %}
    {% if event.eventName %}
        <h3 class="my-3">{{ event.eventName }}</h2>
        <p>Triggered in {{ event.triggeredIn }}</p>
      {% if event.since %}
        <p>Since: {{ event.since }}</p>   
      {% endif %}
        <p>{{ event.description | md }}</p>
    {% else %}
        {% partial "events" items=event %}
    {% endif %}
{% endfor %}

[mjauvin]

[mjauvin]

@LukeTowers @bennothommo any objection to merge this?

[bennothommo]

@mjauvin Before merging, would you be able to do some unit tests? I'd be especially interested to see if it's parsing params that span multiple lines?

[mjauvin]

@bennothommo why would a tag span multiple lines? The @param, @since and @event definitely won't.

[bennothommo]

@mjauvin "event" and "since" likely won't, but it's fairly common for the param tag to span a couple of lines for more complex parameters, or for listing potential parameter values.

[mjauvin]

@bennothommo can you give an example of this? How would it be delimited, by an empty line?

[bennothommo]

@mjauvin This is one example: https://github.com/wintercms/winter/blob/develop/modules/system/classes/SourceManifest.php#L419-L420

It would either be delimited by another tag being defined (like say another @param or @since tag), or it would be delimited by the event doc block ending.

I would say, however, that I'm sure the ReflectionDocBlock library would have this covered if you were to use that instead.

[mjauvin]

Fair enough @bennothommo.

I am not using the ReflectionDocBlock library because the format for our Events doc blocks is not really compatible with the standard format.

[bennothommo]

@mjauvin Fair enough if that's the case, but if you get stuck, it might be worth having a browse through their code and see if they do things differently.

[mjauvin]

I'll modify the @param parser to handle multi-lines.