📝 Add docstrings to issue-345-withany (#619)

* 📝 Add docstrings to `issue-345-withany`

Docstrings generation was requested by @otaviof.

* #618 (comment)

The following files were modified:

* `examples/typed_tools/main.go`
* `mcp/tools.go`

* Update tools.go

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: Ed Zynda <[email protected]>

Author: coderabbitai[bot]

examples/typed_tools/main.go

@@ -21,6 +21,10 @@ type GreetingArgs struct {
 	AnyData any `json:"any_data"`
 }
 
+// main starts the MCP-based example server, registers a typed "greeting" tool, and serves it over standard I/O.
+// 
+// The registered tool exposes a schema for typed inputs (name, age, is_vip, languages, metadata, and any_data)
+// and uses a typed handler to produce personalized greetings. If the server fails to start, an error is printed to stdout.
 func main() {
 	// Create a new MCP server
 	s := server.NewMCPServer(
@@ -76,7 +80,11 @@ func main() {
 	}
 }
 
-// Our typed handler function that receives strongly-typed arguments
+// typedGreetingHandler constructs a personalized greeting from the provided GreetingArgs and returns it as a text tool result.
+//
+// If args.Name is empty the function returns a tool error result with the message "name is required" and a nil error.
+// The returned greeting may include the caller's age, a VIP acknowledgement, the number and list of spoken languages,
+// location and timezone from metadata, and a formatted representation of AnyData when present.
 func typedGreetingHandler(ctx context.Context, request mcp.CallToolRequest, args GreetingArgs) (*mcp.CallToolResult, error) {
 	if args.Name == "" {
 		return mcp.NewToolResultError("name is required"), nil
@@ -110,4 +118,4 @@ func typedGreetingHandler(ctx context.Context, request mcp.CallToolRequest, args
 	}
 
 	return mcp.NewToolResultText(greeting), nil
-}
+}

mcp/tools.go

@@ -1091,8 +1091,10 @@ func WithObject(name string, opts ...PropertyOption) ToolOption {
 	}
 }
 
-// WithArray adds an array property to the tool schema.
-// It accepts property options to configure the array property's behavior and constraints.
+// WithArray returns a ToolOption that adds an array-typed property with the given name to a Tool's input schema.
+// It applies provided PropertyOption functions to configure the property's schema, moves a `required` flag
+// from the property schema into the Tool's InputSchema.Required slice when present, and registers the resulting
+// schema under InputSchema.Properties[name].
 func WithArray(name string, opts ...PropertyOption) ToolOption {
 	return func(t *Tool) {
 		schema := map[string]any{
@@ -1113,8 +1115,9 @@ func WithArray(name string, opts ...PropertyOption) ToolOption {
 	}
 }
 
-// WithAny adds a property of any type to the tool schema.
-// It accepts property options to configure the property's behavior and constraints.
+// WithAny adds an input property named name with no predefined JSON Schema type to the Tool's input schema.
+// The returned ToolOption applies the provided PropertyOption functions to the property's schema, moves a property-level
+// `required` flag into the Tool's InputSchema.Required list if present, and stores the resulting schema under InputSchema.Properties[name].
 func WithAny(name string, opts ...PropertyOption) ToolOption {
 	return func(t *Tool) {
 		schema := map[string]any{}
@@ -1133,7 +1136,8 @@ func WithAny(name string, opts ...PropertyOption) ToolOption {
 	}
 }
 
-// Properties defines the properties for an object schema
+// Properties sets the "properties" map for an object schema.
+// The returned PropertyOption stores the provided map under the schema's "properties" key.
 func Properties(props map[string]any) PropertyOption {
 	return func(schema map[string]any) {
 		schema["properties"] = props