GH-644: implement review suggestions

spring-modulith-docs/src/main/java/org/springframework/modulith/docs/Documenter.java

@@ -1199,14 +1199,37 @@ private Options(@Nullable String outputFolder, boolean clean) {
 			this.clean = clean;
 		}
 
+		/**
+		 * Creates a default {@link Options} instance configuring a default output folder based on the detected build tool (see {@link Options#DEFAULT_LOCATION}).
+		 * Use {@link #withOutputFolder(String)} if you want to customize the output folder.
+		 * Per default the output folder is wiped before any files are written to it.
+		 * Use {@link #withoutClean()} to disable cleaning of the output folder.
+		 *
+		 * @return will never be {@literal null}.
+		 * @see #withoutClean()
+		 * @see #withOutputFolder(String)
+		 */
 		public static Options defaults() {
 			return new Options(DEFAULT_LOCATION, true);
 		}
 
+		/**
+		 * Disables the cleaning of the output folder before any file is written.
+		 *
+		 * @return will never be {@literal null}.
+		 */
 		public Options withoutClean() {
 			return new Options(outputFolder, false);
 		}
 
+		/**
+		 * Configures the output folder for the created files.
+		 * The given directory is wiped before any files are written to it.
+		 *
+		 * @param folder if null the default location based on the detected build system will be used (see {@link Options#DEFAULT_LOCATION}).
+		 * The given folder will be created if it does not exist already. Existing folders are supported as well.
+		 * @return will never be {@literal null}.
+		 */
 		public Options withOutputFolder(String folder) {
 			return new Options(folder, clean);
 		}

spring-modulith-integration-test/src/test/java/org/springframework/modulith/docs/DocumenterTest.java

@@ -83,8 +83,8 @@ void customizesOutputLocation(@TempDir Path outputDirectory) throws IOException
 
 	@Test
 	void shouldCleanOutputLocation(@TempDir Path outputDirectory) throws IOException {
-		Path filePath = createTestFile(outputDirectory);
-		Path nestedFiledPath = createTestFileInSubdirectory(outputDirectory);
+		var filePath = createTestFile(outputDirectory);
+		var nestedFiledPath = createTestFileInSubdirectory(outputDirectory);
 
 		new Documenter(ApplicationModules.of(Application.class), outputDirectory.toString()).writeDocumentation();
 
@@ -95,8 +95,8 @@ void shouldCleanOutputLocation(@TempDir Path outputDirectory) throws IOException
 
 	@Test
 	void shouldNotCleanOutputLocation(@TempDir Path outputDirectory) throws IOException {
-		Path filePath = createTestFile(outputDirectory);
-		Path nestedFiledPath = createTestFileInSubdirectory(outputDirectory);
+		var filePath = createTestFile(outputDirectory);
+		var nestedFiledPath = createTestFileInSubdirectory(outputDirectory);
 
 		new Documenter(ApplicationModules.of(Application.class), Options.defaults().withOutputFolder(outputDirectory.toString()).withoutClean())
 				.writeDocumentation();