Add supported data types documentation and Ballerina Central links for Ballerina Module

[iamvirul]

Purpose

This PR addresses the need to clearly document the supported data types for Ballerina Module functions in WSO2 Integrator: MI. The documentation now explicitly describes which data types are supported at compile time (via the compiler plugin) and how they are mapped at runtime (via the mi-module-gen tool). This resolves issue #1897.

Goals

• Clearly document all supported data types for @mi:Operation annotated functions at compile time
• Explain how supported data types are mapped to MI connector parameters at runtime
• Add direct links to Ballerina Central for the compiler plugin (wso2/mi v0.4.0) and module generator tool (mi_module_gen v0.4.3)
• Improve clarity by making the data type specifications more precise (e.g., map<any> instead of map<...>)

Approach

The documentation has been enhanced in the ballerina-module/overview.md file with the following changes:

1. Added Ballerina Central Links:

   • Added link to the compiler plugin (wso2/mi v0.4.0) when introducing the module import
   • Added link to the module generator tool (mi_module_gen v0.4.3) in the tool pull section
   • Updated references in the "Supported Data Types" section to include direct links to both tools

2. Enhanced Data Type Documentation:

   • Clarified the distinction between compile-time validation (performed by the compiler plugin) and runtime mapping (performed by the mi-module-gen tool)
   • Made data type specifications more precise by replacing generic placeholders (...) with specific syntax ({ } for records, map<any> for maps)
   • Maintained clear separation between primitive and structured types

3. Improved Clarity:

   • Updated the "Supported Data Types" section to explicitly state that the compiler plugin enforces types at compile time
   • Clarified that the mi-module-gen tool maps types to MI connector parameters at runtime
   • Provided clear examples of supported types in both contexts

User stories

• As a developer, I want to know which Ballerina data types are supported when writing @mi:Operation functions so I can write correct code that compiles successfully
• As a developer, I want to understand how my Ballerina types are mapped to MI connector parameters at runtime so I can properly configure my integration flows
• As a developer, I want direct links to the Ballerina Central packages so I can easily access the compiler plugin and module generator tool documentation

Release note

Enhanced Ballerina Module documentation with comprehensive data type support information, including compile-time validation and runtime mapping details. Added direct links to Ballerina Central for the compiler plugin and module generator tool.

Documentation

This PR directly updates the product documentation at:

• en/docs/develop/customizations/ballerina-module/overview.md

The changes improve the existing documentation by adding missing information about supported data types and providing direct links to related Ballerina Central packages.

Training

N/A - This is a documentation update that clarifies existing functionality. No training content changes are required.

Certification

N/A - This is a documentation enhancement that does not introduce new features or change existing behavior. The changes only clarify existing functionality.

Marketing

N/A - This is a documentation improvement that does not require marketing content.

Automation tests

• Unit tests

  N/A - Documentation-only change

• Integration tests

  N/A - Documentation-only change

Security checks

• Followed secure coding standards in http://wso2.com/technical-reports/wso2-secure-engineering-guidelines? N/A (Documentation-only change)

• Ran FindSecurityBugs plugin and verified report? N/A (Documentation-only change)

• Confirmed that this PR doesn't commit any keys, passwords, tokens, usernames, or other secrets? Yes

Samples

N/A - This PR does not include or modify any code samples. The existing code examples in the documentation remain unchanged and continue to demonstrate the correct usage of supported data types.

Related PRs

None

Migrations (if applicable)

N/A - Documentation-only change, no migration required

Test environment

• Documentation was reviewed and tested locally using MkDocs
• All markdown links were verified to be accessible
• Documentation structure and formatting were validated

Summary by CodeRabbit

• Documentation
  • Expanded module overview with a Supported Data Types section, compile-time validation rules for annotated operations, and runtime type-mapping explanation for module-generated connectors.
  • Added extensive examples (primitive, JSON/XML, record) with diagnostics and usage.
  • Added a module-generation workflow: CLI steps, generated-artifact guidance, visuals, and registry links.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[CLAassistant]

All committers have signed the CLA.

[coderabbitai]

Walkthrough

Expanded the Ballerina module overview: added Ballerina Central links, Supported Data Types, compile-time validation rules for @mi:Operation, runtime type mappings for mi-module-gen, multiple annotated-function examples (primitive/JSON/XML/record), and a "Generate the module" workflow with CLI usage and generated-artifact details.

Changes

Cohort / File(s)

Summary

Documentation: Ballerina module overview en/docs/develop/customizations/ballerina-module/overview.md

Added Ballerina Central links for mi-module-gen and wso2/mi; expanded "Write Ballerina" with Supported Data Types and compile-time validation for @mi:Operation (parameter/return type tables, diagnostics examples, multiple code examples); documented runtime mappings of primitive and structured Ballerina types to connector metadata/UI with a runtime example; added Examples (primitive, JSON/XML, record) and a "Generate the module" workflow with CLI sample and generated artifacts; wording/formatting edits.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐰 I hopped through docs and CLI bright,
I sorted types till stars took flight,
I stitched examples, tables, and more,
A module garden by the door,
Tiny paws, big documentation delight.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main changes: adding documentation for supported data types and Ballerina Central links for the Ballerina Module.
Description check	✅ Passed	The PR description comprehensively covers all required template sections with relevant details, providing clear purpose, goals, approach, user stories, and appropriate N/A responses for non-applicable sections.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 4c3420e and 756b34e.

📒 Files selected for processing (1)

• en/docs/develop/customizations/ballerina-module/overview.md

🔇 Additional comments (2)

en/docs/develop/customizations/ballerina-module/overview.md (2)

53-53: Excellent integration of Ballerina Central links.

The documentation now clearly directs developers to both the wso2/mi_module_gen tool and wso2/mi module on Ballerina Central. The links are well-positioned in context (pull step at line 53, import step at line 66, and conceptual explanation at line 86), making them easily discoverable.

Also applies to: 66-66, 86-86

---

99-99: Markdown formatting is now correct.

The sections properly use heading levels (##### Examples and ##### Runtime example) instead of bold emphasis, satisfying Markdownlint MD036. This maintains proper document structure.

Also applies to: 142-142

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 7a831c2 and 1c36546.

📒 Files selected for processing (1)

• en/docs/develop/customizations/ballerina-module/overview.md (3 hunks)

🧰 Additional context used

🪛 markdownlint-cli2 (0.18.1)

en/docs/develop/customizations/ballerina-module/overview.md

99-99: Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)

---

144-144: Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)

🔇 Additional comments (4)

en/docs/develop/customizations/ballerina-module/overview.md (4)

53-53: Link to Ballerina Central for mi-module-gen is clear and actionable.

The reference to the mi-module-gen tool on Ballerina Central (v0.4.3) helps users discover and verify the tool version, aligning with the PR goal.

---

66-66: Link to Ballerina Central for wso2/mi is consistent and helpful.

The reference to the wso2/mi module (v0.4.0) on Ballerina Central allows users to explore the compiler plugin directly, supporting the documentation goal.

---

146-150: Clarify function modifier consistency in examples.

The runtime example uses remote function (line 147), but the compile-time validation examples use public function. This inconsistency could confuse users about which modifier to use when writing @mi:Operation functions.

The distinction should clarify: are remote function examples showing the generated connector output, or should users also write remote functions? If this is generated output, the example context could be clearer.

Please clarify whether:

1. Users should write remote or public functions with @mi:Operation
2. Whether the runtime example at line 147 represents generated connector code (in which case it should be labeled as such)
3. Whether both modifiers are supported equally

---

84-162: Excellent comprehensive documentation of supported data types and runtime behavior.

The new "Supported Data Types" section effectively documents compile-time validation constraints and runtime mapping behavior, directly addressing the PR objectives. The table format is clear, examples are practical, and the Ballerina Central links provide users with direct access to module specifications.

The separation between compile-time (wso2/mi plugin v0.4.0) and runtime (mi-module-gen v0.4.3) responsibilities is well-articulated, making the documentation precise and actionable.

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 10135b4 and 4c3420e.

📒 Files selected for processing (1)

• en/docs/develop/customizations/ballerina-module/overview.md

[RDPerera]

LGTM