If you browse through Java projects in GitHub you find often files named package.html with content like:
<HTML>
<BODY>
Utils: Helpful things, which shouldn't implement against an Interface.
<p>
@since 1.0
</BODY>
</HTML>
The meaning is very clear. This file describes which type of Java classes should placed there. The syntax allows several Annotations to extend the information. Another nice effect, mostly developers not aware about it, is the usage as placeholder. Let me fast explain what I mean with it. Of course we are in the context of java development and in the moment you start your project, you have to create the directory structure. When you use a build tool like Maven, you could start your project with running an archetype to do the job. If you use the common IDEs like NetBeans you can choose from plenty templates. After this step is follows mostly a fist commit to a Source Control Management system (SCM) like git or Subversion. But there is a small problem. Git don’t let you commit empty directories. As solution many developers create hidden files named .keept. This practice is common and well established, but when you create empty packages and place instead your package.htm you solve two problems. As first Git let you commit your directory and you already include a documentation for developers which content is expected in this package.
Less common are package-info.java files, introduced in Java 5. The purpose of this files is equal to package.htm – it’s just a newer approach and the official recommendation from oracle to describe a package. Some developers have the idea using a java file for API documentation is an abuse, because they don’t contain code. The big different are the package annotations, you can use. Another argument is since Java 9 and the project Jigsaw for modularization is introduced a module-info.java file, located in the root of your project. This file is a descriptor of the whole module. There are defined used dependencies, accessible packages and other things. In my opinion is a good style to not mix up things and use as descriptor the java files. I believe the new approach brings more flexibility. For example you can place in the package-info.java compile time annotations, instead into the classes. This centralization avoid missing annotaions and reduce duplication's.
If your project contain both package.html and package-info.java, the prefferd source for JavaDoc will be always package-info.java. If you want to create the package-info.java file in Eclipse IDE by using a standard class, you will fail, because of the Java convention. To solve the problem, you just need to got to the package where you want to place your info file and create a new package. This package you can name as package-info.java.
Top comments (0)