Fix issue 1858

[manojasomarathna]

Fixes #1858: Document common mediator attributes for all mediators.

Purpose

Provide documentation for the common description attribute in mediators, which exists for readability but was previously undocumented.

Goals

• Establish a central reference for common mediator attributes.
• Reduce confusion for end-users by providing consistent documentation.

Approach

• Added common-mediator-attributes.md to document all common attributes including description.
• Updated index.md in the mediators reference folder to link to the new common attributes page.
• Updated observability setup documentation to reflect XML declaration updates for Axis2 payloads.

User Stories

End-users can now reference common mediator attributes clearly, improving the readability and usability of mediator documentation.

Release Notes

• Added documentation for common mediator attributes.
• Updated mediators index page with links to the new reference.

Documentation Changes

• en/docs/reference/mediators/common-mediator-attributes.md
• en/docs/reference/mediators/index.md
• en/docs/observe-and-manage/setting-up-cloud-native-observability-on-a-vm.md

Testing

• No functional code changes; only documentation updates.
• Verified Markdown formatting and internal links.

Please review and provide feedback if any updates are needed.

[coderabbitai]

Walkthrough

Adds documentation for common mediator attributes (specifically the description attribute), creates a new mediators reference page, and updates observability setup documentation with an XML declaration configuration step for Axis2 payloads.

Changes

Cohort / File(s)	Summary
Common Mediator Attributes Documentation en/docs/reference/mediators/common-mediator-attributes.md, en/docs/reference/mediators/index.md	Introduces new reference documentation for mediator common attributes, including the description attribute with usage examples. Creates mediators index page with links to common attributes reference.
Observability Configuration Update en/docs/observe-and-manage/setting-up-cloud-native-observability-on-a-vm.md	Adds new configuration step (Step 1.5) to enable XML declaration in outgoing XML payloads with Axis2 property settings and Synapse handler configuration.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

These are documentation-only changes with straightforward content additions. No functional code or logic modifications present.

Poem

🐰 A common thread now woven bright,
Through mediator docs, plain as light—
The description attribute takes its place,
No more confusion to erase!
XML declarations flow with grace,
Our docs now bloom, a joyful space! 📚✨

Pre-merge checks and finishing touches

❌ Failed checks (2 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	Title 'Fix issue 1858' is vague and generic, lacking specificity about what the fix actually addresses.	Revise the title to be more specific about the change, such as 'Document common mediator attributes' or 'Add documentation for common mediator attributes'.
Out of Scope Changes check	❓ Inconclusive	First file modification to 'setting-up-cloud-native-observability-on-a-vm.md' (adding Step 1.5 and Axis2/Prometheus configuration) appears unrelated to documenting common mediator attributes from issue #1858.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Changes fully address issue #1858 by creating dedicated documentation for common mediator attributes, eliminating the need to repeat these across individual mediator pages.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description check	✅ Passed	The PR description is mostly complete and follows the template structure with all required sections present and filled with substantive content addressing the issue.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

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

---

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.}

[manojasomarathna]

Added common mediator attributes documentation as discussed.
Please review and let me know if any further updates are needed.

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

en/docs/reference/mediators/common-mediator-attributes.md (1)

1-40: Clean up excessive whitespace and HTML entities in code blocks.

The documentation content effectively addresses the PR objective. However, there are formatting issues:

1. Excessive blank lines (lines 2-4, 6-8, 10-12, 14-16, 25-26, 28-30): Multiple consecutive blank lines create unnecessary clutter and can result in inconsistent rendering. Reduce to single blank lines for section separation.

2. HTML entity in XML code (line 35): The   entity should be replaced with regular spaces/tabs for proper XML formatting. Code blocks should contain literal XML syntax, not HTML entities.

-\# Common Mediator Attributes
-
-
-
-Some attributes are common to all mediators in WSO2 Integrator: MI. These attributes are used to improve the readability and maintainability of mediation logic and do not change the functional behavior of the mediator.
-
-
-
-\## description
-
-
-
-The `description` attribute can be used with any mediator to provide a human-readable explanation of what the mediator does.
-
-
-
-\### Purpose
+# Common Mediator Attributes
+
+Some attributes are common to all mediators in WSO2 Integrator: MI. These attributes are used to improve the readability and maintainability of mediation logic and do not change the functional behavior of the mediator.
+
+## description
+
+The `description` attribute can be used with any mediator to provide a human-readable explanation of what the mediator does.
+
+### Purpose

 ```xml
 <log description="Logs the incoming request payload">
-&nbsp;   <property name="message" value="Request received"/>
+    <property name="message" value="Request received"/>
 </log>

</blockquote></details>

</blockquote></details>

<details>
<summary>📜 Review details</summary>

**Configuration used**: CodeRabbit UI

**Review profile**: CHILL

**Plan**: Pro

<details>
<summary>📥 Commits</summary>

Reviewing files that changed from the base of the PR and between 7a831c202e87888d1c4ea27f83389abf19fd3301 and d11ca9463eb79b3d99fe876e55f8672d0004e636.

</details>

<details>
<summary>📒 Files selected for processing (3)</summary>

* `en/docs/observe-and-manage/setting-up-cloud-native-observability-on-a-vm.md` (1 hunks)
* `en/docs/reference/mediators/common-mediator-attributes.md` (1 hunks)
* `en/docs/reference/mediators/index.md` (1 hunks)

</details>

<details>
<summary>🔇 Additional comments (4)</summary><blockquote>

<details>
<summary>en/docs/reference/mediators/common-mediator-attributes.md (1)</summary><blockquote>

`9-23`: **Clear documentation of the common `description` attribute.**

The content effectively explains the `description` attribute's purpose and correctly notes that it affects readability only, not runtime behavior. The documentation aligns well with the PR objective to address issue #1858.

</blockquote></details>
<details>
<summary>en/docs/observe-and-manage/setting-up-cloud-native-observability-on-a-vm.md (2)</summary><blockquote>

`111-123`: **Verify markdown code fence closure and section organization.**

There appears to be a structural issue with the code blocks in this section:

1. **Potential unclosed XML code fence**: Line 115 opens a code block with ` ```xml ` and contains the property configuration, but there's no visible closing fence (` ``` `) before line 119 where a TOML code block begins.

2. **Section organization**: Confirm whether Step 1.5 (XML declaration) should be positioned before or after the synapse handler configuration shown on lines 119-123, as these are related but distinct configuration steps.

Please verify that:
- The XML code block on lines 115-118 is properly closed with a fence
- The section ordering and logical flow are correct for users following the setup guide

---

`111-118`: **Clarify the relevance of XML declaration configuration in observability setup guide.**

Step 1.5 about enabling XML declaration appears to be a general Axis2 configuration rather than specific to Grafana-based observability setup (metrics, logging, or tracing). 

Please clarify:
- How does XML declaration in outgoing payloads relate to the Grafana observability setup process?
- Should this be included in this guide, or would it be better suited in a general Axis2 configuration or payload transformation guide?
- Is there a specific observability use case that requires XML declaration to be set at this step?

This context will help assess whether the section placement and framing are appropriate.

</blockquote></details>
<details>
<summary>en/docs/reference/mediators/index.md (1)</summary><blockquote>

`1-22`: **Verify link path and assess index page scope.**

The new mediators index page establishes a clear entry point to the mediators documentation. However:

1. **Link verification**: Line 19 references `common-mediator-attributes.md` as a relative link. Confirm this path is correct for files located in `en/docs/reference/mediators/`.

2. **Scope completeness**: The index currently only includes the Common Attributes section. Will this page eventually contain:
   - Links to individual mediator documentation?
   - Categories of mediators (routing, transformation, etc.)?
   - Other reference information?

If this is the initial version and more content will be added later, that's fine. If this is the complete scope, it may be redundant with the Common Attributes page. Please clarify the intended role of this index page.

</blockquote></details>

</blockquote></details>

</details>

<!-- This is an auto-generated comment by CodeRabbit for review status -->