VS Code not showing hover documentation for Java annotations like @Entity and @Data

by 
# VS Code Not Showing Hover Documentation for Java Annotations: Technical Postmortem

### ## Summary
A Java developer using VS Code for Spring Boot experienced missing hover documentation (Javadoc) for common annotations like `@Entity`, `@Table`, and `@Data`. The project used JDK 17, Maven, Spring Boot, JPA/Hibernate, and Lombok. While compilation and autocomplete worked normally, annotation hovers failed to display documentation.

### ## Root Cause
The issue was caused by two primary factors:
- Lombok-generated code was not processed by the Java Language Server due to missing annotation processing configuration
- Enterprise libraries (JPA/Hibernate) lacked source attachments in the Maven repository configuration

### ## Why This Happens in Real Systems
Common systemic reasons for this failure:
- **Annotation Processing Gap**: Tools like Lombok generate code at compile time. Without explicit configuration for IDE annotation processors, metadata needed for Javadoc hovers isn't produced.
- **Binary-Only Dependencies**: Enterprise dependencies (e.g., Hibernate) are often consumed as binary JARs without attached sources.
- **Mixed Tooling Environments**: Build tools (Maven/Gradle) don't automatically synchronize annotation processing settings with IDEs.
- **Implicit Source Handling**: Many developers assume dependency sources are resolved automatically, but IDEs often require explicit source attachment.

### ## Real-World Impact
Operational consequences:
- **Slower Development**: Engineers manually search documentation for annotations, disrupting flow.
- **Increased Errors**: Lack of immediate documentation leads to misconfigured annotations (e.g., incorrect JPA attributes).
- **Onboarding Friction**: New team members struggle with unclear annotation behaviors.
- **Tool Distrust**: Developers lose confidence in VS Code's Java capabilities.

## Example Configuration Fix
Add these configurations to `settings.json` and `pom.xml`:
```json:settings.json
"java.configuration.updateBuildConfiguration": "automatic",
"java.completion.forcedVisibilities": [
  "public",
  "protected",
  "private"
],
"java.import.gradle.enabled": false,
"java.import.maven.enabled": true

Crucial Lombok Maven setup:



org.projectlombok
lombok
1.18.24
provided






org.apache.maven.plugins
maven-compiler-plugin
3.11.0



org.projectlombok
lombok
1.18.24

How Senior Engineers Fix It

Systematic resolution approach:

  1. Enable Annotation Processing: Configure Lombok explicitly in Maven/Gradle and verify IDE settings (java.annotationProcessing.enabled)
  2. Attach Sources: Use Maven to download source JARs (mvn dependency:sources)
  3. Verify Dependency Sources:
    • Check “Maven Dependencies” in VS Code’s Java Projects view
    • Manually attach source JARs to binary dependencies
  4. Flush Caches: Run VS Code commands Java: Clean Java Language Server Workspace and Java: Force Java Compilation
  5. Validation: Hover over standard Java annotations (e.g., @Override) to isolate project-specific issues

Why Juniors Miss It

Common oversight patterns:

  • Assumption of Automation: Believing IDEs automatically resolve annotation metadata/sources
  • Lombok Transparency: Not understanding Lombok’s compile-time nature vs. IDE runtime requirements
  • Tooling Silos: Focusing solely on build tool configuration without IDE integration checks
  • Symptoms Normalization: Accepting missing documentation as tool limitations without investigation
  • Cache Blind Spot: Overlooking IDE/internal cache persistence effects even after config fixes