What does the javadoc comment above package declaration do?

Question

When I create a new class in Eclipse and check "Generate comments", I get this:

/** * */ package my_package; /** * @author myname * */ public class MyClass { }

What's the point of the comment above the package declaration? It doesn't seem to be included anywhere (if I put something there) when I generate javadocs. Is it just Eclipse misfiring, or a weird Eclipse setting I have, or is it there for a reason?

If I do that in IntelliJ, it complains that it's "dangling" which is usually reserved for occasions when you've misplaced them. I've also never seen them used there before. So yes, this looks like Eclipse misfiring — Michael
– Michael, Commented Jun 14, 2022 at 13:39
It does a couple of things. Some IDEs use that text as an on-hover text bubble when you're hovering over a commented item. When you generate an actual javadoc, it uses that text in the description of the class, method, or field, etc. — Ryan
– Ryan, Commented Jun 14, 2022 at 13:44

Michael · Accepted Answer · 2022-06-14 14:21:21Z

5

From Oracle

A doc comment is written in HTML and must precede a class, field, constructor or method declaration

There are also package-level comments which are placed in a file called package-info.java, which are used for generating documentation such as for the package java.time.

Trying to include a package-level comment in a regular source file seems like a bug. The docs state "you can place your comments in one of the following files...". IntelliJ also shows the warning "Dangling Javadoc comment" when package-level comments are placed in a regular source file.

edited Jun 14, 2022 at 14:21

answered Jun 14, 2022 at 13:52

Michael

44.5k12 gold badges97 silver badges143 bronze badges

Sign up to request clarification or add additional context in comments.

4 Comments

Mark Rotteveel Over a year ago

I'm not sure if it is only a convention. As far as I can tell, javadoc only processes package level javadoc from package.html or package-info.java. See "Package Comment Files" (this is for Java 7, but I couldn't find the equivalent for a newer Java version). And adding a package javadoc in any "normal" .java file will be ignored by the javadoc tool.

Michael Over a year ago

@MarkRotteveel This is the 8 equivalent. It looks pretty much the same, though I only skimmed it docs.oracle.com/javase/8/docs/technotes/tools/windows/…

Mark Rotteveel Over a year ago

Thanks, to be honest, I only tried finding it in the Java 17 docs :)

Michael Over a year ago

@MarkRotteveel Anyway, thanks. That documentation seems conclusive enough. "you can place your comments in one of the following files" sort of implies that the list is exhaustive. Updated my answer

Ashish Patil · Accepted Answer · 2022-06-14 15:31:13Z

For me, The comments generated above package are because of preference settings:

If I un-check Automatically add comments for new methods, types, modules ,packages and files, it is not appearing for me.

Moreover, if I edit Files comments, then File level comments are not appearing whenever I generate comments.

Collectives™ on Stack Overflow

What does the javadoc comment above package declaration do?

2 Answers 2

4 Comments

Comments

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

4 Comments

Comments

Related