IntelliJ IDEA 和 Eclipse 中 Javadoc 不显示的解决方法：需正确配置 JDK 的 docs/api 路径，确保版本匹配；Eclipse 需先附加 source 再附加 javadoc；Gradle 项目需启用 downloadJavadoc；自定义类需有 package-info.java 并手动生成 Javadoc。

IntelliJ IDEA 里 Javadoc 不显示？先检查 JDK 是否附带 docs

IDEA 默认不会自动下载 JDK 文档，即使你装了完整版 JDK，src.zip 和 docs/api 也可能没一起解压或挂载。不配 docs 路径，Ctrl+Q（Quick Documentation）就只能看到方法签名，看不到 @param、@return 这些内容。

• 打开 File → Project Structure → SDKs，选中你的 JDK，展开 Documentation path 项
• 点击 + 添加路径，指向 JDK 安装目录下的 docs/api（例如：/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home/docs/api 或 C:\Program Files\Java\jdk-21\docs\api）
• 如果本地没有 docs/api，去 Oracle 官网 或 OpenJDK GitHub 发布页 下载对应版本的 docs-all.zip，解压后取其中 docs/api 目录
• 别用 src.zip 冒充 docs——它只含源码，不生成 Javadoc 渲染效果

Eclipse 中鼠标悬停无注释？关键在 Attach source and Javadoc 的顺序

Eclipse 不像 IDEA 那样默认识别 docs 路径，必须手动为 rt.jar（或模块化后的 java.base）显式附加 Javadoc。而且顺序很重要：先 attach source，再 attach javadoc，否则 javadoc 会失效。

• 打开 Preferences → Java → Installed JREs，选中 JDK → Edit…
• 展开 rt.jar（Java 8）或 modules（Java 9+），找到 Source attachment，设为 src.zip
• 在同一节点下，展开 Javadoc location，填入本地 docs/api 路径；若用在线文档，填 https://www.php.cn/link/d0df036bf29fd4db6e3fadab6b31471517/docs/api/（注意末尾斜杠）
• 改完必须点 Validate——Eclipse 会尝试加载首页 index.html，失败就说明路径错或网络不通
• Java 9+ 模块化后，rt.jar 消失，要对每个核心模块（如 java.base）单独 attach，但通常只需配 java.base 就够用

Gradle/Maven 项目里第三方库没注释？靠依赖坐标里的 -javadoc.jar

IDE 只有在 classpath 中的 jar 包附带同名 -javadoc.jar 时，才能解析出注释。Maven 中央仓库大多提供，但 Gradle 默认不下载；有些私有仓库或老旧库压根没发布 javadoc。

JavaStoryDevelop

你接手一个需求时，是不是经常这样："改一个小字段 → 结果把不相关的代码也改了"、"需求说得很模糊 → 做着做着发现跑偏了"、"数据库加个字段 → 上线才发现漏了数据兼容"、"做了个新功能 → 一个月后自己都忘了当时怎么设计的"、"写到一半被中断 → 再回来不知道从哪继续"；这个 Skill 就是专门解决这些问题的。 它会自动探测你的项目环境（JDK、Spring Boot、ORM、数据库、前端框架），记在

下载

• Maven 用户不用额外操作，只要依赖声明没加 <classifier>javadoc</classifier>，IDEA/Eclipse 通常能自动关联（前提是仓库有且网络通）
• Gradle 用户需在 build.gradle 加配置：

  dependencies {
      implementation 'com.google.guava:guava:33.2.0-jre'
  }
  // 启用自动下载
  configurations.all {
      resolutionStrategy {
          activateDependencyLocking()
          // 强制下载 javadoc 和 sources
          transitive = true
      }
  }
  idea {
      module {
          downloadJavadoc = true
          downloadSources = true
      }
  }

• 如果某库始终不显示注释，用 ./gradlew dependencies --configuration compileClasspath 看是否拉到了 -javadoc.jar；没有的话，可能是仓库没发布，或坐标写错了（比如用了 -sources.jar 当 -javadoc.jar）

自定义类的 Javadoc 在 IDE 里不生效？和 package-info.java 与编译参数有关

自己写的类，哪怕写了完整的 Javadoc 注释，IDE 也不一定实时显示——常见原因是没生成 javadoc 输出，或者包级注释 package-info.java 缺失导致包路径识别异常。

立即学习“Java免费学习笔记（深入）”；

• 确保类文件顶部有标准注释块，且 public 类/方法才被 Javadoc 工具提取（private 方法注释不会进生成结果）
• 包根目录下必须有 package-info.java，哪怕只写

  /**
   * 包描述。
   */
  package com.example.utils;

  ——否则部分 IDE 无法将源码与生成的 docs 关联
• 命令行运行 javadoc -d docs/api src/main/java/com/example/utils/*.java 手动生成一次，再把 docs/api 路径配进 IDE，比等 IDE 自动扫描更可靠
• IDE 缓存有时会卡住：删掉 .idea/misc.xml 里的 javadocPath 相关字段，重启 IDEA

最常被忽略的是 JDK 版本和 docs 版本严格匹配——用 JDK 21 编译，却配了 JDK 17 的 docs，@apiNote 这类新标签会直接不渲染，连带整个注释块变空白。配之前，先确认 java -version 和 docs URL 路径里的版本号完全一致。