Skip to content

Commit

Permalink
Javadoc stuff.
Browse files Browse the repository at this point in the history
  • Loading branch information
LambdAurora committed Oct 22, 2023
1 parent f5d2379 commit f8263b2
Show file tree
Hide file tree
Showing 5 changed files with 67 additions and 3 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@
* and each phase can have a defined ordering. Each event phase is identified, ordering is done
* by explicitly stating that event phase {@code A} will run before event phase {@code B}, for example.
* See {@link Event#addPhaseOrdering(Comparable, Comparable)} for more information.
* <p>
*
* <h2>Example: Registering listeners</h2>
* <p>
* The most common use of an event will be registering a listener which is executed by the event. To register a listener,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@
* For the examples below, we will be using an event where the listener type is the interface
* {@code ScaryEvents.Spooked}. {@code Spooked} is a functional interface where the first parameter is a ghost and the
* second parameter is the entity being spooked. The entity being spooked is the invoking parameter.
* <p>
*
* <h2>Why make an event parameter invoking?</h2>
* <p>
* A good reason to make an event parameter invoking is when the event directly relates to an action performed on a
Expand Down Expand Up @@ -78,7 +78,7 @@
*
* <pre>{@code
* @ParameterInvokingEvent
* public static final Event<String, ScaryEvents.Spooked> SPOOKED = [event factory].create(ScaryEvents.Spooked.class, listeners -> (ghost, spookedEntity) -> {
* public static final Event<String, ScaryEvents.Spooked> SPOOKED = [event manager].create(ScaryEvents.Spooked.class, listeners -> (ghost, spookedEntity) -> {
* // Since this event is parameter invoking, does the entity being spooked implement `Spooked`?
* if (spookedEntity instanceof ScaryEvents.Spooked listener) {
* // Since the entity implements the listener, invoke the listener on the entity.
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
/*
* Copyright 2023 Yumi Project
*
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at https://mozilla.org/MPL/2.0/.
*/

/**
* <h2>The Event Invoker APIs</h2>
* <p>
* To call its listeners, an {@link dev.yumi.commons.event.Event Event} object stores an invoker implementation of
* its listener interface. This functional approach to the event invocation problem avoids the need of slow reflection
* to call the listeners or the need to create a new event implementation for each kind of event.
* To be able to generate such invoker implementation the event is given an invoker factory which takes the listeners as
* input and returns the invoker implementation.
* <p>
* Usually invoker factories are simple {@link java.util.function.Function functions}, but this event API additionally offers
* the {@link dev.yumi.commons.event.invoker.InvokerFactory InvokerFactory} interface which still has the factory function but
* is also given the type of listener interface in its constructor.
* <p>
* As such, the event invoker APIs provide a {@link dev.yumi.commons.event.invoker.DefaultInvokerFactory default invoker factory}
* which is able to generate at runtime invoker implementations for simple common cases that may be found in most invoker implementations.
* Please refer to its documentation for more details about which cases are handled.
*
* @see dev.yumi.commons.event
* @see dev.yumi.commons.event.invoker.InvokerFactory
* @see dev.yumi.commons.event.invoker.DynamicInvokerFactory
* @see dev.yumi.commons.event.invoker.DefaultInvokerFactory
*/

package dev.yumi.commons.event.invoker;
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
/*
* Copyright 2023 Yumi Project
*
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at https://mozilla.org/MPL/2.0/.
*/

/**
* <h2>The Event APIs</h2>
* <p>
* Events are used to represents specific points in a program which may need other softwares to listen and call code when
* those points are reached.
* <p>
* Said events are represented using the {@link dev.yumi.commons.event.Event Event} object which stores its listeners,
* and events are created and managed with the help of an {@link dev.yumi.commons.event.EventManager event manager}.
*
* @see dev.yumi.commons.event.Event
* @see dev.yumi.commons.event.EventManager
*/

package dev.yumi.commons.event;
10 changes: 10 additions & 0 deletions libraries/event/src/main/java/module-info.java
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,16 @@
* file, You can obtain one at https://mozilla.org/MPL/2.0/.
*/

/**
* <h2>The Yumi Commons Event Framework</h2>
* <p>
* Events are used to represents specific points in a program which may need other softwares to listen and call code when
* those points are reached.
* <p>
* Said events are represented using the {@link dev.yumi.commons.event.Event Event} object which stores its listeners,
* and events are created and managed with the help of an {@link dev.yumi.commons.event.EventManager event manager}.
*/

module dev.yumi.commons.event {
requires dev.yumi.commons.core;
requires dev.yumi.commons.collections;
Expand Down

0 comments on commit f8263b2

Please sign in to comment.