Some Eclipse Foundation services are deprecated, or will be soon. Please ensure you've read this important communication.

Bug 193726

Summary:	[1.5][javadoc] Missing javadoc comment warning not reported for package-info.java
Product:	[Eclipse Project] JDT	Reporter:	Frederic Fusier <frederic_fusier>
Component:	Core	Assignee:	JDT-Core-Inbox <jdt-core-inbox>
Status:	CLOSED WONTFIX	QA Contact:
Severity:	normal
Priority:	P5
Version:	3.3
Target Milestone:	---
Hardware:	PC
OS:	Windows XP
Whiteboard:	stalebug

Description Frederic Fusier

2007-06-21 10:19:27 EDT

Using 3.3 RC4 but also happen in 3.2...

1) Create a package-info.java with no javadoc comment
2) Modify compiler option to report Missing Javadoc Comments at the Default level
3) Rebuild the project
4) You get no warning although you should have a warning on the package-info 
   package declaration saying that there's a missing comment...

Comment 1 Eric Jodet

2008-05-23 01:09:26 EDT

Searching http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html,
I did not find anything saying that the package-info.java must contain a javadoc comment:
"package-info.java - Can contain a package declaration, package annotations, package comments and Javadoc tags."

We may also consider that though suffixed .java, the package-info.java file may not be considered as a "standard" java file, as it has a documentation purpose.
Hence, this file might not be part of the missing javadoc comments validation.

(but we may want to be able to validate content (tags) if any, as it's currently the case)

Frederic?

Comment 2 Frederic Fusier

2008-06-05 11:32:42 EDT

In the 'Where tags can be used' section: http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#wheretags
one can read:
Package Documentation Tags
Package tags are tags that can appear in the documentation comment for a package (which resides in the source file named package.html or package-info.java). The @serial tag can only be used here with the include or exclude argument.

Also, in following doc: http://java.sun.com/docs/books/jls/third_edition/html/packages.html#7.4.1.1

The 'Discussion' paragraph states that:
"If this file is present, the documentation generation tool should look for the package documentation comment immediately preceding the (possibly annotated) package declaration in package-info.java."

If I understand well, both means that the package-info.java may have a javadoc comment, hence the compiler is supposed to warn the user if it is missing when the appropriate preferences is set.

Comment 3 Eclipse Genie

2020-01-28 06:46:54 EST

This bug hasn't had any activity in quite some time. Maybe the problem got resolved, was a duplicate of something else, or became less pressing for some reason - or maybe it's still relevant but just hasn't been looked at yet. As such, we're closing this bug.

If you have further information on the current state of the bug, please add it and reopen this bug. The information can be, for example, that the problem still occurs, that you still want the feature, that more information is needed, or that the bug is (for whatever reason) no longer relevant.

--
The automated Eclipse Genie.