Jelly's Event Javadoc outline

eventJavadoc.md

Current Template

Event handlers in Terasology always follow the same pattern. For instance, an handler that listens for a

@ReceiveEvent(components = DisplayNameComponent.class, priority = EventPriority.PRIORITY_LOW)
public void onActivation(ActivateEvent event, EntityRef entity, HealthComponent component1, LocationComponent component2) {
  // do something
}

And a regular javadoc template for this event might look something like this:

/**
 * 
 * @param event
 * @param entity
 * @param component1
 * @param component2
 */

Template Suggestion

However, this template doesn't actually contain all the information, and the details for the entity and event are repetative. As such I've been ommitting them and using a different layout. The full template looks like this:

/**
 * <Description of what the handler does>
 * 
 * Called when <When the event is sent>
 * Filters on {@link Component1}, {@link Component1}
 * Priority {@link EventPriority#value}
 * 
 * @see EventName
 */

This allows the javadoc to include the actually useful information whilst not including the information that is redundant (eg, the EntityRef parameter). It is especially effective when the event being sent also includes which entity it should be sent against.

This could also be integrated to be an 'offical' part of javadoc by adding custom tags such as @filters, @priority and similar.

Example

Taken from the EnemyManager in GooeyDefence

/**
 * Destroys an enemy when it dies.
 * <p>
 * Called when an entity reaches zero health.
 * Filters on {@link GooeyComponent}
 * Priority {@link EventPriority#PRIORITY_TRIVIAL}
 *
 * @see EntityDeathEvent
 */
@ReceiveEvent(priority = EventPriority.PRIORITY_TRIVIAL)
public void onEntityDeath(EntityDeathEvent event, EntityRef entity, GooeyComponent component) {
  destroyEnemy(entity);
}