What would you like to be added:
Analyze the javadocs state in SDK.
Add javadocs across the SDK.
Core API modules (api/, types/, annotations/)
Implementation modules (impl/)
Fluent API modules (fluent/, experimental/fluent/)
Utility modules (mermaid/, generators/)
Why is this needed:
So the developers are better guided when working on implementation.
Offers guidance on correct use of the code.
Analysis summary
Analyzed using IBM Bob
Overview
This document provides a structured, prioritized breakdown of JavaDoc
improvement tasks for the Serverless Workflow Java SDK.
Each unit is designed to be completed independently in 2-4 hours
and groups 5-15 related classes for efficient documentation.
TIER 1: CRITICAL - Main Entry Points & Core APIs
Unit 1.1: Fluent API - Core Workflow Builders
Priority: CRITICAL
Impact: Highest - Primary developer entry point
Scope:
Document fluent builder pattern and method chaining
Provide complete usage examples for each builder
Explain builder lifecycle and immutability
Cross-reference related builders
Files:
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/WorkflowBuilder.java
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/TaskBuilder.java
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/DoTaskBuilder.java
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/SetTaskBuilder.java
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/SwitchTaskBuilder.java
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/ForTaskBuilder.java
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/ForkTaskBuilder.java
Dependencies: None
Unit 1.2: Fluent API - Call & Communication Tasks
Priority: CRITICAL
Impact: High - HTTP/gRPC integration patterns
Scope:
Document HTTP call patterns (GET, POST, PUT, DELETE, etc.)
Explain authentication integration
Provide OpenAPI and gRPC examples
Document error handling in calls
Files:
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/CallTaskBuilder.java
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/CallHttpTaskBuilder.java
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/CallOpenAPITaskBuilder.java
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/CallGrpcTaskBuilder.java
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/HttpMethodBuilder.java
Dependencies: None
Unit 1.3: Fluent API - Event Handling
Priority: CRITICAL
Impact: High - Event-driven workflow patterns
Scope:
Document event emission patterns
Explain event listening and filtering
Provide pub/sub examples
Document CloudEvents integration
Files:
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/EmitTaskBuilder.java
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/ListenTaskBuilder.java
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/EventFilterBuilder.java
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/EmitEventPropertiesBuilder.java
Dependencies: None
Unit 1.4: Fluent API - Error Handling & Control Flow
Priority: CRITICAL
Impact: High - Resilience patterns
Scope:
Document try/catch/retry patterns
Explain error matching and handling
Provide retry strategy examples
Document raise task usage
Files:
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/TryTaskBuilder.java
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/CatchBuilder.java
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/RetryBuilder.java
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/RaiseTaskBuilder.java
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/ErrorBuilder.java
Dependencies: None
Unit 1.5: Core Runtime - Application & Definition
Priority: CRITICAL
Impact: Highest - Core runtime entry points
Scope:
Document application lifecycle and configuration
Explain workflow definition loading and validation
Provide complete initialization examples
Document thread pool and executor configuration
Files:
impl/core/src/main/java/io/serverlessworkflow/impl/WorkflowApplication.java
impl/core/src/main/java/io/serverlessworkflow/impl/WorkflowDefinition.java
impl/core/src/main/java/io/serverlessworkflow/impl/WorkflowApplicationBuilder.java
impl/core/src/main/java/io/serverlessworkflow/impl/WorkflowReader.java
Dependencies: None
Unit 1.6: Core Runtime - Instance & Execution
Priority: CRITICAL
Impact: Highest - Workflow execution control
Scope:
Document instance creation and lifecycle
Explain execution control (start, suspend, resume, cancel)
Provide async/sync execution examples
Document state management
Files:
impl/core/src/main/java/io/serverlessworkflow/impl/WorkflowInstance.java
impl/core/src/main/java/io/serverlessworkflow/impl/WorkflowExecutor.java
impl/core/src/main/java/io/serverlessworkflow/impl/WorkflowContext.java
impl/core/src/main/java/io/serverlessworkflow/impl/WorkflowStatus.java
Dependencies: Unit 1.5
Unit 1.7: Annotations - All Annotation Types
Priority: CRITICAL
Impact: High - Extension and customization
Scope:
Document each annotation's purpose and usage
Provide extension examples
Explain annotation processing
Document custom task/executor registration
Files:
annotations/src/main/java/io/serverlessworkflow/annotations/*.java (all annotation files)
Include: @WorkflowTask, @TaskExecutor, @ExpressionLanguage, etc.
Dependencies: None
TIER 2: HIGH - Core Interfaces & Persistence
Unit 2.1: Core Interfaces - Task Execution
Priority: HIGH
Impact: High - Custom task implementation
Scope:
Document TaskExecutor interface and lifecycle
Explain custom task executor creation
Provide implementation examples
Document executor registration
Files:
impl/core/src/main/java/io/serverlessworkflow/impl/executors/TaskExecutor.java
impl/core/src/main/java/io/serverlessworkflow/impl/executors/AbstractTaskExecutor.java
impl/core/src/main/java/io/serverlessworkflow/impl/executors/TaskExecutorFactory.java
impl/core/src/main/java/io/serverlessworkflow/impl/executors/TaskContext.java
Dependencies: Unit 1.6
Unit 2.2: Core Interfaces - Expression & Evaluation
Priority: HIGH
Impact: High - Expression language integration
Scope:
Document ExpressionFactory interface
Explain expression evaluation context
Provide custom expression language examples
Document JQ integration
Files:
impl/core/src/main/java/io/serverlessworkflow/impl/expressions/ExpressionFactory.java
impl/core/src/main/java/io/serverlessworkflow/impl/expressions/ExpressionEvaluator.java
impl/core/src/main/java/io/serverlessworkflow/impl/expressions/ExpressionContext.java
impl/core/src/main/java/io/serverlessworkflow/impl/expressions/JQExpressionFactory.java
Dependencies: None
Unit 2.3: Core Interfaces - Event Handling
Priority: HIGH
Impact: High - Event-driven architecture
Scope:
Document EventConsumer interface
Explain event subscription patterns
Provide custom event handler examples
Document CloudEvents integration
Files:
impl/core/src/main/java/io/serverlessworkflow/impl/events/EventConsumer.java
impl/core/src/main/java/io/serverlessworkflow/impl/events/EventPublisher.java
impl/core/src/main/java/io/serverlessworkflow/impl/events/EventFilter.java
impl/core/src/main/java/io/serverlessworkflow/impl/events/CloudEventAdapter.java
Dependencies: None
Unit 2.4: Persistence API - Core Interfaces
Priority: HIGH
Impact: High - State persistence patterns
Scope:
Document persistence SPI
Explain state serialization/deserialization
Provide custom persistence implementation examples
Document transaction handling
Files:
impl/persistence/api/src/main/java/io/serverlessworkflow/impl/persistence/WorkflowPersistence.java
impl/persistence/api/src/main/java/io/serverlessworkflow/impl/persistence/WorkflowStateStore.java
impl/persistence/api/src/main/java/io/serverlessworkflow/impl/persistence/PersistenceContext.java
impl/persistence/api/src/main/java/io/serverlessworkflow/impl/persistence/StateSerializer.java
Dependencies: Unit 1.6
Unit 2.5: Utility Classes - Core Utilities
Priority: HIGH
Impact: Medium - Helper functions
Scope:
Document utility methods and their use cases
Provide usage examples
Explain error handling utilities
Document validation helpers
Files:
impl/core/src/main/java/io/serverlessworkflow/impl/utils/WorkflowUtils.java
impl/core/src/main/java/io/serverlessworkflow/impl/utils/ErrorUtils.java
impl/core/src/main/java/io/serverlessworkflow/impl/utils/ValidationUtils.java
impl/core/src/main/java/io/serverlessworkflow/impl/utils/JsonUtils.java
Dependencies: None
Unit 2.6: Error Handling - Error Types & Handlers
Priority: HIGH
Impact: High - Error management patterns
Scope:
Document standard error types
Explain custom error definition
Provide error handling examples
Document error propagation
Files:
impl/core/src/main/java/io/serverlessworkflow/impl/errors/WorkflowError.java
impl/core/src/main/java/io/serverlessworkflow/impl/errors/ErrorHandler.java
impl/core/src/main/java/io/serverlessworkflow/impl/errors/StandardErrors.java
impl/core/src/main/java/io/serverlessworkflow/impl/errors/ErrorMatcher.java
Dependencies: None
TIER 3: MEDIUM - Experimental & Visualization
Unit 3.1: Experimental Types - Type System
Priority: MEDIUM
Impact: Medium - Advanced type features
Scope:
Document experimental type system
Explain type validation and conversion
Provide usage examples with warnings
Document stability expectations
Files:
experimental/types/src/main/java/io/serverlessworkflow/experimental/types/*.java
Include type definitions, validators, and converters
Dependencies: None
Unit 3.2: Mermaid Visualization - Diagram Generation
Priority: MEDIUM
Impact: Medium - Documentation and visualization
Scope:
Document diagram generation API
Explain customization options
Provide rendering examples
Document supported diagram types
Files:
mermaid/src/main/java/io/serverlessworkflow/mermaid/MermaidGenerator.java
mermaid/src/main/java/io/serverlessworkflow/mermaid/DiagramBuilder.java
mermaid/src/main/java/io/serverlessworkflow/mermaid/NodeRenderer.java
mermaid/src/main/java/io/serverlessworkflow/mermaid/FlowchartGenerator.java
Dependencies: Unit 1.5
Unit 3.3: Lifecycle & Events - Event System
Priority: MEDIUM
Impact: Medium - Monitoring and observability
Scope:
Document lifecycle event types
Explain event subscription patterns
Provide monitoring examples
Document event payload structure
Files:
impl/core/src/main/java/io/serverlessworkflow/impl/lifecycle/LifecycleEvent.java
impl/core/src/main/java/io/serverlessworkflow/impl/lifecycle/WorkflowLifecycle.java
impl/core/src/main/java/io/serverlessworkflow/impl/lifecycle/TaskLifecycle.java
impl/core/src/main/java/io/serverlessworkflow/impl/lifecycle/EventPublisher.java
Dependencies: Unit 2.3
Unit 3.4: Fluent API - Advanced Builders
Priority: MEDIUM
Impact: Medium - Advanced workflow patterns
Scope:
Document wait, run, and container task builders
Explain scheduling and timing
Provide subprocess examples
Document container integration
Files:
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/WaitTaskBuilder.java
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/RunTaskBuilder.java
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/RunContainerTaskBuilder.java
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/RunScriptTaskBuilder.java
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/RunWorkflowTaskBuilder.java
Dependencies: Unit 1.1
Unit 3.5: Fluent API - Authentication & Security
Priority: MEDIUM
Impact: Medium - Security patterns
Scope:
Document authentication builder patterns
Explain OAuth2/OIDC configuration
Provide security examples
Document credential management
Files:
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/AuthenticationBuilder.java
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/BasicAuthBuilder.java
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/BearerAuthBuilder.java
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/OAuth2Builder.java
Dependencies: Unit 1.2
TIER 4: LOW - Implementation Details
Unit 4.1: Generator Utilities
Priority: LOW
Impact: Low - Code generation tools
Scope:
Document code generation utilities
Explain type generation from schemas
Provide generator configuration examples
Files:
generators/types/src/main/java/io/serverlessworkflow/generators/*.java
Dependencies: None
Unit 4.2: Internal Executors - HTTP Implementation
Priority: LOW
Impact: Low - Internal implementation
Scope:
Document HTTP executor implementation
Explain request/response handling
Document authentication integration
Files:
impl/http/src/main/java/io/serverlessworkflow/impl/executors/http/*.java
Focus on public extension points only
Dependencies: Unit 2.1
Unit 4.3: Internal Executors - gRPC & OpenAPI
Priority: LOW
Impact: Low - Internal implementation
Scope:
Document gRPC executor implementation
Explain OpenAPI integration
Document schema resolution
Files:
impl/grpc/src/main/java/io/serverlessworkflow/impl/executors/grpc/*.java
impl/openapi/src/main/java/io/serverlessworkflow/impl/executors/openapi/*.java
Dependencies: Unit 2.1
Unit 4.4: Expression Implementations - JQ & Custom
Priority: LOW
Impact: Low - Internal implementation
Scope:
Document JQ expression implementation
Explain custom expression language integration
Files:
impl/jq/src/main/java/io/serverlessworkflow/impl/expressions/jq/*.java
Dependencies: Unit 2.2
Unit 4.5: Model Implementations - Jackson Integration
Priority: LOW
Impact: Low - Internal serialization
Scope:
Document Jackson model implementation
Explain serialization/deserialization
Document custom type handling
Files:
impl/model/src/main/java/io/serverlessworkflow/impl/model/jackson/*.java
Dependencies: None```
What would you like to be added:
Analyze the javadocs state in SDK.
Add javadocs across the SDK.
Why is this needed:
So the developers are better guided when working on implementation.
Offers guidance on correct use of the code.
Analysis summary
Analyzed using IBM Bob