listeners.get(i).dispatch();
    }
  }

  /**
   * A special purpose queue/executor that dispatches listener events serially on a configured
   * executor. Each event can be added and dispatched as separate phases.
   *
   * <p>This class is very similar to {@link SequentialExecutor} with the exception that events can
   * be added without necessarily executing immediately.
   */

import java.util.Set;
import java.util.Spliterator;
import java.util.function.Consumer;
import org.jspecify.annotations.Nullable;

/**
 * An immutable sorted set with one or more elements. TODO(jlevy): Consider separate class for a
 * single-element sorted set.
 *
 * @author Jared Levy
 * @author Louis Wasserman
 */
@GwtCompatible
@SuppressWarnings({"serial", "rawtypes"})

En este caso, podrías querer documentar cómo esa API externa *debería* verse. Qué *path operation* debería tener, qué cuerpo debería esperar, qué response debería devolver, etc.

## Una aplicación con callbacks { #an-app-with-callbacks }

Veamos todo esto con un ejemplo.

Imagina que desarrollas una aplicación que permite crear facturas.

///

### Usa el form data { #use-the-form-data }

/// tip | Consejo

La instance de la clase de dependencia `OAuth2PasswordRequestForm` no tendrá un atributo `scope` con el string largo separado por espacios, en su lugar, tendrá un atributo `scopes` con la lista real de strings para cada scope enviado.

No estamos usando `scopes` en este ejemplo, pero la funcionalidad está ahí si la necesitas.

///

      Paths.get(file(checkstyleIdeConfig).getPath()),
      StandardCopyOption.REPLACE_EXISTING
    )

    // There are some rules that we only want to enable in an IDE. These
    // are extracted to a separate file, and merged into the IDE-specific
    // Checkstyle config.
    Node xmlFragment = parseXml(checkstyleIdeFragment)

    // Edit the copy so that IntelliJ can copy with it
    modifyXml(checkstyleIdeConfig, { xml ->

    }
  }

  /** Read a value as bytes without interpretation of its contents. */
  fun readUnknown(): ByteString = source.readByteString(bytesLeft)

  override fun toString(): String = path.joinToString(separator = " / ")

  companion object {
    /**
     * A synthetic value that indicates there's no more bytes. Values with equivalent data may also

        index += 8;
        if (msg.getCommand() == ServerMessageBlock.SMB_COM_READ_ANDX) {
            /*
             * SmbComReadAndXResponse reads directly from the stream into separate byte[] b.
             */
            final SmbComReadAndXResponse raxr = (SmbComReadAndXResponse) msg;
            final int length = msg.getLength() - raxr.getDataLength();

Nesse caso, você poderia querer documentar como essa API externa *deveria* ser. Que *operação de rota* ela deveria ter, que corpo ela deveria esperar, que resposta ela deveria retornar, etc.

## Um aplicativo com callbacks { #an-app-with-callbacks }

Vamos ver tudo isso com um exemplo.

Imagine que você desenvolve um aplicativo que permite criar faturas.

Only a single connection is ever made between two servers.
Likely this means that this connection will not be able to saturate network bandwidth.
Therefore, using this for large payloads will likely be slower than using a separate connection,
and other connections will be blocked while the large payload is being sent.

## Handlers & Routes

Handlers have a predefined Handler ID.

	// Copy all immediate files and testdata directories between
	// the package being tested and the source root.
	pkgpath = ""
	for element := range strings.SplitSeq(finalPkgpath, string(filepath.Separator)) {
		if debug {
			log.Printf("copying %s", pkgpath)
		}
		pkgpath = filepath.Join(pkgpath, element)
		dst := filepath.Join(dstbase, pkgpath)
		src := filepath.Join(cwd, pkgpath)