Documentation fixes and improvements.

CHANGELOG.md

@@ -4,7 +4,13 @@ All notable changes to this project will be documented in this file.
 
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased](https://github.com/alexdlaird/java-ngrok/compare/2.3.2...HEAD)
+## [Unreleased](https://github.com/alexdlaird/java-ngrok/compare/2.3.3...HEAD)
+
+## [2.3.3](https://github.com/alexdlaird/java-ngrok/compare/2.3.2...2.3.3) - 2024-11-10
+
+### Added
+
+- Documentation improvements.
 
 ## [2.3.2](https://github.com/alexdlaird/java-ngrok/compare/2.3.1...2.3.2) - 2024-11-08
 

README.md

@@ -64,7 +64,7 @@ a [`CreateTunnel`](https://javadoc.io/doc/com.github.alexdlaird/java-ngrok/lates
 which can be built
 through [its Builder](https://javadoc.io/doc/com.github.alexdlaird/java-ngrok/latest/com.github.alexdlaird.ngrok/com/github/alexdlaird/ngrok/protocol/CreateTunnel.Builder.html))
 that allows us to pass additional properties that
-are [supported by `ngrok`](https://ngrok.com/docs/agent/config/v2/#tunnel-configurations).
+are supported by `ngrok`, [as documented here](https://javadoc.io/doc/com.github.alexdlaird/java-ngrok/latest/com.github.alexdlaird.ngrok/com/github/alexdlaird/ngrok/NgrokClient.html#tunnel-configurations).
 
 ### `ngrok`'s Edge
 To use [`ngrok`'s Edge](https://ngrok.com/docs/network-edge/edges/) with `java-ngrok`, first

build.gradle

@@ -11,7 +11,7 @@ plugins {
 }
 
 group "com.github.alexdlaird"
-version "2.3.2"
+version "2.3.3"
 
 java {
     withJavadocJar()

src/main/java/com/github/alexdlaird/ngrok/NgrokClient.java

@@ -67,10 +67,8 @@
  * </pre>
  *
  * <p>The {@link NgrokClient#connect(CreateTunnel) NgrokClient.connect()} method can also take a {@link CreateTunnel}
- * (which can be built through {@link CreateTunnel.Builder its Builder}), which allows us to configure the tunnel when
- * it is created, for instance adding authentication, a subdomain, or other additional
- * <a href="https://ngrok.com/docs/agent/config/v2/#tunnel-configurations" target="_blank">tunnel configurations that
- * are supported by ngrok</a>.
+ * (which can be built through {@link CreateTunnel.Builder its Builder}), which allows us to pass additional tunnel
+ * configurations that are supported by ngrok, <a href="#tunnel-configurations">as documented here</a>.
  *
  * <p><p><code>java-ngrok</code> is compatible with <code>ngrok</code> v2 and v3, but by default it will install v3. To
  * install v2 instead, set the version with {@link JavaNgrokConfig.Builder#withNgrokVersion(NgrokVersion)} and
@@ -155,6 +153,26 @@
  *         .build();
  * final Tunnel fileserverTunnel = ngrokClient.connect(fileserverCreateTunnel);
  * </pre>
+ * <h3 id="tunnel-configurations">Tunnel Configurations</h3>
+ * It is possible to configure the tunnel when it is created, for instance adding authentication, a subdomain, or other
+ * additional <a href="https://ngrok.com/docs/agent/config/v2/#tunnel-configurations" target="_blank">tunnel
+ * configurations that are supported by ngrok</a>. This is accomplished by using {@link CreateTunnel.Builder} to set
+ * what properties will be used when the tunnel is created.
+ *
+ * <p>Here is an example that opens a tunnel with subdomain <code>foo</code>, requires basic authentication for
+ * requests, and defines a circuit breaker.
+ *
+ * <pre>
+ * final NgrokClient ngrokClient = new NgrokClient.Builder().build();
+ *
+ * final CreateTunnel createTunnel = new CreateTunnel.Builder()
+ *         .withSubdomain("foo")
+ *         .withAuth("username:password"")
+ *         .withCircuitBreaker(50)
+ *         .build();
+ *
+ * final Tunnel tunnel = ngrokClient.connect(createTunnel);
+ * </pre>
  * <h2>Integration Examples</h2>
  * <code>java-ngrok</code> is useful in any number of integrations, for instance to test locally without having to
  * deploy or configure. Here are some common usage examples.
@@ -195,7 +213,7 @@ private NgrokClient(final Builder builder) {
      * target="_blank">tunnel definition in ngrok's config file</a> matches the given
      * {@link CreateTunnel.Builder#withName(String)}, it will be loaded and used to start the tunnel. When
      * {@link CreateTunnel.Builder#withName(String)} is not set and a "java-ngrok-default" tunnel definition exists in
-     * <code>ngrok</code>'s config, it will be loaded and use. Any properties defined on {@link CreateTunnel} will
+     * <code>ngrok</code>'s config, it will be loaded and used. Any properties defined on {@link CreateTunnel} will
      * override properties from the loaded tunnel definition.
      *
      * <p>If <code>ngrok</code> is not installed at {@link JavaNgrokConfig}'s <code>ngrokPath</code>, calling this

src/main/java/com/github/alexdlaird/ngrok/protocol/CreateTunnel.java

@@ -32,10 +32,7 @@
  *         .withAddr(5000)
  *         .build();
  *
- * final HttpClient httpClient = new DefaultHttpClient.Builder().build()
- * final Response<SomePOJOResponse> postResponse = httpClient.post("http://localhost:4040/api/tunnels",
- *                                                                 createTunnel,
- *                                                                 Tunnel.class);
+ * final Tunnel httpTunnel = ngrokClient.connect(createTunnel);
  * </pre>
  * <h2><code>ngrok</code> Version Compatibility</h2>
  * <code>java-ngrok</code> is compatible with <code>ngrok</code> v2 and v3, but by default it will install v3. To

src/main/java/overview.html

@@ -65,7 +65,7 @@ <h2>Getting Around</h2>
 
 <ul>
     <li>{@link com.github.alexdlaird.ngrok.NgrokClient} - Get started using <code>java-ngrok</code>, most common uses cases just require the default client behavior</li>
-    <li>{@link com.github.alexdlaird.ngrok.conf.JavaNgrokConfig} - Configure configuration for <code>java-ngrok</code></li>
+    <li>{@link com.github.alexdlaird.ngrok.conf.JavaNgrokConfig} - Configure the {@link com.github.alexdlaird.ngrok.NgrokClient}, {@link com.github.alexdlaird.ngrok.process.NgrokProcess}, {@link com.github.alexdlaird.ngrok.installer.NgrokInstaller}, and other parts of <code>java-ngrok</code></li>
     <li>{@link com.github.alexdlaird.ngrok.process.NgrokProcess} - Advanced usage of the <code>ngrok</code> process</li>
 </ul>