Improve docs on Dev Mode

core/devmode-spi/src/main/java/io/quarkus/dev/spi/HotReplacementContext.java

@@ -27,28 +27,43 @@ public interface HotReplacementContext {
     boolean isTest();
 
     /**
-     * Will return true if this is the remote side of a remote dev session
+     * Returns the type of the development mode
      * 
-     * @return
+     * @return the dev mode type
      */
     DevModeType getDevModeType();
 
     /**
+     * Scans for changed source files, and restarts if detected.
      *
+     * @param userInitiated If this scan was initiated by a user action (e.g. refreshing a browser)
      * @return {@code true} if a restart was performed, {@code false} otherwise
      * @throws Exception
      */
     boolean doScan(boolean userInitiated) throws Exception;
 
+    /**
+     * Adds a task that is run before a live reload scan is performed.
+     *
+     * @param runnable The task to run
+     */
     void addPreScanStep(Runnable runnable);
 
     /**
      * The consumer is invoked if only files which don't require restart are modified.
      *
      * @param consumer The input is a set of changed file paths
-     * @see HotDeploymentWatchedFileBuildItem#isRestartNeeded()
+     * @see io.quarkus.deployment.builditem.HotDeploymentWatchedFileBuildItem#isRestartNeeded()
      */
     void consumeNoRestartChanges(Consumer<Set<String>> consumer);
 
+    /**
+     * This method returns a list of changed files compared to the provided map of file names to hashes.
+     *
+     * This is needed for remote dev mode, it is unlikely to be useful for anything else
+     *
+     * @param fileHashes The file hashes
+     * @return A set of changed files
+     */
     Set<String> syncState(Map<String, String> fileHashes);
 }

docs/src/main/asciidoc/writing-extensions.adoc

@@ -1820,6 +1820,30 @@ If you need more customization capabilities than registering a serializer or a d
 you can produce a CDI bean that implements `io.quarkus.jsonb.JsonbConfigCustomizer` via an `AdditionalBeanBuildItem`.
 More info about customizing JSON-B can be found on the JSON guide link:rest-json#configuring-json-support[Configuring JSON support]
 
+=== Integrating with Development Mode
+
+There are various APIS that you can use to integrate with development mode, and to get information about the current state.
+
+==== Handling restarts
+
+When Quarkus is starting the `io.quarkus.deployment.builditem.LiveReloadBuildItem` is guaranteed to be present that gives
+information about this start, in particular:
+
+- Is this a clean start or a live reload
+- If this is a live reload which changed files / classes triggered the reload
+
+It also provides a global context map you can use to store information between restarts, without needing to resort to
+static fields.
+
+==== Triggering Live Reload
+
+Live reload is generally triggered by a HTTP request, however not all applications are HTTP applications and some extensions
+may want to trigger live reload based on other events. To do this you need to implement `io.quarkus.dev.spi.HotReplacementSetup`
+in your runtime module, and add a `META-INF/services/io.quarkus.dev.spi.HotReplacementSetup` that lists your implementation.
+
+On startup the `setupHotDeployment` method will be called, and you can use the provided `io.quarkus.dev.spi.HotReplacementContext`
+to initiate a scan for changed files.
+
 === Testing Extensions
 
 Testing of Quarkus extensions should be done with the `io.quarkus.test.QuarkusUnitTest` JUnit 5 extension.