Small update

docs/free-port.adoc

@@ -1,5 +1,7 @@
 :page-title: Free Port
 :page-description: Extends JUnit Jupiter with `@FreePort` to get a free port.
+:xp-demo-dir: ../src/demo/java
+:demo: {xp-demo-dir}/org/junitpioneer/jupiter/resource/FreePortDemo.java
 
 == Introduction
 
@@ -17,13 +19,5 @@ To get the `FreePort` as an argument on a test just add the annotation to your t
 
 [source,java]
 ----
-
-@ExtendWith(FreePortExtension.class)
-class ServerTest {
-
-    @Test
-    void test(FreePort port) {
-        // use port.number() or check before using port.isFreeNow()
-    }
-}
+include::{demo}[tag=basic_free_port_example]
 ----

src/demo/java/org/junitpioneer/jupiter/resource/FreePortDemo.java

@@ -0,0 +1,29 @@
+/*
+ * Copyright 2016-2023 the original author or authors.
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License v2.0 which
+ * accompanies this distribution and is available at
+ *
+ * http://www.eclipse.org/legal/epl-v20.html
+ */
+
+package org.junitpioneer.jupiter.resource;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.net.ServerSocket;
+
+import org.junit.jupiter.api.Test;
+
+public class FreePortDemo {
+
+	// tag::basic_free_port_example[]
+	@Test
+	void testFreePort(@NewPort ServerSocket port) {
+		assertThat(port).isNotNull();
+		assertThat(port.isClosed()).isFalse();
+	}
+	// end::basic_free_port_example[]
+
+}

src/main/java/org/junitpioneer/jupiter/FreePort.java → src/main/java/org/junitpioneer/jupiter/resource/FreePort.java

@@ -8,15 +8,12 @@
  * http://www.eclipse.org/legal/epl-v20.html
  */
 
-package org.junitpioneer.jupiter;
+package org.junitpioneer.jupiter.resource;
 
 import java.io.IOException;
 import java.net.ServerSocket;
 import java.util.List;
 
-import org.junitpioneer.jupiter.resource.Resource;
-import org.junitpioneer.jupiter.resource.ResourceFactory;
-
 public final class FreePort implements ResourceFactory<ServerSocket> {
 
 	public FreePort() {

src/main/java/org/junitpioneer/jupiter/resource/NewPort.java

@@ -0,0 +1,22 @@
+/*
+ * Copyright 2016-2023 the original author or authors.
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License v2.0 which
+ * accompanies this distribution and is available at
+ *
+ * http://www.eclipse.org/legal/epl-v20.html
+ */
+
+package org.junitpioneer.jupiter.resource;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+@New(FreePort.class)
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.PARAMETER)
+public @interface NewPort {
+}

src/test/java/module-info.java

@@ -24,13 +24,14 @@
 	exports org.junitpioneer.jupiter.params;
 	exports org.junitpioneer.jupiter.json;
 	exports org.junitpioneer.jupiter.converter;
+	exports org.junitpioneer.jupiter.resource;
 
 	opens org.junitpioneer.vintage to org.junit.platform.commons;
 	opens org.junitpioneer.jupiter to org.junit.platform.commons, nl.jqno.equalsverifier;
 	opens org.junitpioneer.jupiter.cartesian to org.junit.platform.commons;
 	opens org.junitpioneer.jupiter.issue to org.junit.platform.commons;
 	opens org.junitpioneer.jupiter.params to org.junit.platform.commons;
-	opens org.junitpioneer.jupiter.resource to org.junit.platform.commons;
+	opens org.junitpioneer.jupiter.resource to nl.jqno.equalsverifier, org.junit.platform.commons;
 	opens org.junitpioneer.jupiter.json to org.junit.platform.commons, com.fasterxml.jackson.databind;
 	opens org.junitpioneer.jupiter.converter to org.junit.platform.commons;
 

src/test/java/org/junitpioneer/jupiter/FreePortExtensionTests.java → src/test/java/org/junitpioneer/jupiter/resource/FreePortExtensionTests.java

@@ -8,7 +8,7 @@
  * http://www.eclipse.org/legal/epl-v20.html
  */
 
-package org.junitpioneer.jupiter;
+package org.junitpioneer.jupiter.resource;
 
 import static org.junitpioneer.testkit.PioneerTestKit.executeTestClass;
 import static org.junitpioneer.testkit.assertion.PioneerAssert.assertThat;
@@ -18,7 +18,6 @@
 import org.assertj.core.api.Assertions;
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Test;
-import org.junitpioneer.jupiter.resource.New;
 import org.junitpioneer.testkit.ExecutionResults;
 
 @DisplayName("Free port extension")
@@ -34,7 +33,7 @@ void testFreePortParameterResolution() {
 	static class FreePortTestCase {
 
 		@Test
-		void testFreePortParameterResolution(@New(FreePort.class) ServerSocket port) {
+		void testFreePortParameterResolution(@NewPort ServerSocket port) {
 			Assertions.assertThat(port).isNotNull();
 		}