docs: Enhance Javadoc documentation across core components

[vero-code]

Description

This pull request significantly enhances and standardizes the Javadoc documentation for key classes and methods across 21 files within the core package, specifically focusing on the LLM flow and Event handling components.

Key Changes & Improvements

• Comprehensive Javadoc Coverage: Added or expanded Javadoc comments for critical methods and classes, ensuring clear explanations of their purpose, parameters, return values, and potential exceptions. This includes, but is not limited to, methods in LlmFlow (e.g., callLlm, handleBeforeModelCallback, handleAfterModelCallback, runOneStep, run, runLive), AgentTransfer, ExampleUtils, and various callback-related classes.
• Standardization & Readability:
  • Converted numerous single-line comments into proper Javadoc blocks where appropriate, improving consistency and automated documentation generation.
  • Addressed instances where comments were missing or represented by empty quotes, filling in necessary documentation.
  • Ensured consistent use of Javadoc tags (e.g., @param, @return, @throws, {@link}) and standard formatting for better readability and navigation within IDEs and generated documentation.

Rationale & Value Add

This work aims to significantly improve the overall readability, maintainability, and comprehensibility of the codebase. Enhanced Javadoc documentation:

• Facilitates Onboarding: Makes it easier for new developers to understand complex flows and APIs quickly.
• Reduces Errors: Provides clearer guidance on method usage, reducing potential for misuse.
• Boosts Maintainability: Simplifies future debugging, refactoring, and feature development by providing immediate context for code elements.

This contribution aligns with best practices for code documentation and directly supports the long-term health and usability of the adk project.

[vorburger]

LGTM.

[shukladivyansh]

Hi Veronika!

Thanks for the PR. Really appreciate the efforts to improve the docs.

We won't be able to merge this PR for a few reasons.

1. Too noisy - We want our docstrings to be concise and meaningful
2. Alignment with adk-python - We lean on adk-python for being the source of truth and the docstrings shouldn't deviate from them
3. AI Generated - This PR feels AI generated. It's ok to generate the first draft using AI but we won't accept docs without further revision and human input.

[vero-code]

Hi Divyansh!

Thank you so much for the detailed feedback! I've simplified the Javadoc, removed redundant parts, and aligned it with the adk-python style where applicable. I'm happy to address any further comments.

[vorburger]

LGTM.

[Poggecci]

Thank you very much for this contribution! Requested a few changes but after that, LGTM!

[vero-code]

Hi Alejandro,

Thank you for the review! I have made all the requested changes to the Javadoc comments. Please take another look.

[Poggecci]

Submission failed due to formatting. Apologies for the churn, but would you mind running the Google formatter on your local changes?

We have #210 to eventually do this as part of local build, but it hasn't been merged yet so you'll have to follow any of the instructions here to run the formatter:
https://github.com/google/google-java-format?tab=readme-ov-file#from-the-command-line
(I believe the simplest way would just be to copy lines 194-212 of

adk-java/pom.xml

Line 194 in f53600e

<plugin>

into your local adk pom.xml and run the build command to have the source files get formatted. Then just remove the changes from your pom.xml and commit the now formatted files).

[vero-code]

Great idea with the plugin! I’ve committed the formatted code — thanks for the detailed instructions on the “simplest way”. That really helped!