[Feat]: Add Example_* test functions for pkg.go.dev documentation #209
Description
Is your feature request related to a problem? Please describe.
The package documentation currently does not include any testable examples (Example_* functions) that render as runnable snippets on pkg.go.dev.
While the repository contains usage examples in the README and doc.go comments, those snippets are not executable and are not validated by the Go toolchain. As a result, they do not appear as function-level examples in the generated documentation and may become outdated without being detected by tests.
Providing idiomatic testable examples would improve documentation quality and make the public API easier to understand directly from pkg.go.dev.
Describe the solution you'd like
Add example_test.go files following Go’s ExampleXxx / ExampleType_Method naming convention, starting with the a2a/ core types package.
Testable examples would:
- Render automatically as runnable examples on pkg.go.dev at the type/function level.
- Be validated by
go testthrough// Output:comments. - Serve as both documentation and lightweight regression protection.
- Improve discoverability and clarity of the public API.
Proposed initial examples for the a2a/ package:
| Function / Type | Example would demonstrate |
|---|---|
NewMessage |
Creating a basic user message with text parts |
NewMessageForTask |
Creating a message referencing an existing task |
NewSubmittedTask |
Initializing a task from an initial message |
TaskState.Terminal() |
Checking whether a state is terminal |
UnmarshalEventJSON |
Deserializing a streaming event using the kind discriminator |
NewError / WithDetails |
Constructing structured A2A errors |
Examples would use package a2a_test where appropriate to demonstrate the public API as an external consumer would use it.
Describe alternatives you've considered
- Expanding README examples — helpful for high-level guidance, but they are not validated by the toolchain and do not appear in function-level documentation on pkg.go.dev.
- Adding examples inside existing
_test.gofiles — this would mix unit tests with documentation examples, reducing separation of concerns. A dedicatedexample_test.gofile is the idiomatic Go approach.
Additional context
I would be happy to open a PR and implement the initial set of examples for the a2a/ package if this approach aligns with the project’s direction.
Additional packages such as a2aclient/ and a2asrv/ could be addressed in follow-up PRs to keep the initial contribution focused and easy to review.
Code of Conduct
- I agree to follow this project's Code of Conduct