如何自定义 JavaDoc 中的“概览”页面？

Question

I'd like the " Overview " page of my library's javadoc to essentially be a user/API guide for the entire JAR. I know that adding a package-info.java class to a package allows you to write package-level javadocs, but what about at the jar-level ?

I know I could put a README.md in my project's root, but I like to think of README's as a doc for library developers (that is, people who will be maintaining the library). But the JavaDocs are API guides for people who will be using the library.

Answer 1

You can create an overview HTML file and place it anywhere you like in your source tree. The convention is to call it overview.html and place it at the root of your tree, but you are certainly not obligated to do so. In fact, you can create multiple overview files for different purposes. When you generate your javadocs, you use the -overview flag and pass it the path to the target overview file.

You can find more information about overview file requirements here .

Answer 2

When you are using Maven and its plugin for JavaDoc :

Put a file named overview.html into folder src/main/javadoc and run the command mvn javadoc:javadoc ; the JavaDoc files are written into folder target/site/apidocs .

This is also possible when you want to generate JavaDoc files for the Unit Tests: Put a file named overview.html into folder src/test/javadoc and run the command mvn javadoc:test-javadoc ; the JavaDoc files are written into folder target/site/testapidocs .