Eclipse生成的包声明上方Javadoc注释有什么作用？

该注释是Eclipse默认代码模板的冗余遗留占位，不属于Java标准规定的有效Javadoc位置，填写的内容不会被Javadoc工具收录是正常表现，既不是个人配置异常，也不是Javadoc本身的设计要求。

• Javadoc工具的解析逻辑有明确规则：只有紧挨着Java代码元素（类、方法、字段、包声明等）正上方的/** */格式注释，才会被识别为对应元素的关联文档注释。包声明是Java源码文件中的第一个正式代码结构，它上方的注释没有绑定任何可生成文档的代码元素，属于孤立注释，会被Javadoc工具直接忽略，不会出现在任何输出的文档结果中。
• 标准的包级Javadoc有固定存放位置：不需要写在单个Java类的包声明上方，正确做法是在对应包的目录下创建名为package-info.java的文件，将包的整体功能说明、版本约束等内容写在该文件的包声明前，同包下所有类的Javadoc页面都会自动关联这份包说明。早期JDK版本支持在包目录下放置package.html编写包文档，目前该方式已经被package-info.java替代。
• Eclipse生成这段空注释属于模板设计遗留问题：最初设计新建类模板时，这个位置是预留给文件级头注释（比如团队规范要求的版权声明、开源许可证标识、文件变更记录等非API文档内容）的占位，但错误地使用了Javadoc专用的/** */格式，而非普通块注释/* */，很容易让使用者误以为这是有效的Javadoc写入位置。

不需要这个冗余占位的话，可以直接手动删除现有文件里的这段空注释，也可以修改Eclipse默认配置永久移除：打开配置路径Window -> Preferences -> Java -> Code Style -> Code Templates，找到「New Java files」对应的模板，删除包声明上方的空Javadoc片段后保存，后续新建类就不会再生成这段无效内容。如果需要保留文件头位置放置版权类内容，将注释格式改为普通块注释即可，不要使用双星号开头的Javadoc格式，避免后续维护时产生混淆。

内容的提问来源于stack exchange，提问作者H.v.M.