Replace the placeholder router doc string and module header that still call StableRouteRouter a placeholder

[mikewheeleer]

Update the StableRouteRouter struct doc and migrate-events TODO header to reflect shipped behaviour

Description

The #[contract] pub struct StableRouteRouter in src/lib.rs still carries the doc string "StableRoute router contract — placeholder for routing logic. In production this would integrate with path payments and liquidity data." The contract is no longer a placeholder: it has registration, fee/bounds/liquidity config, cooldowns, an oracle role, a governance timelock, a reentrancy guard, liquidity consumption, and metrics. The stale "placeholder" framing misleads new contributors and auditors about the contract's maturity. This issue rewrites the struct doc to describe the real router and updates the top-of-file #![allow(deprecated)] events-migration note to point at the tracked migration work rather than reading as an open TODO with no owner.

Requirements and context

• Repository scope: StableRoute-Org/Stableroute-contracts only.
• Rewrite the StableRouteRouter struct doc comment to accurately summarize the implemented capabilities and the intended path-payment integration as future work, not as "this is only a placeholder."
• Refresh the file-header comment so the deprecated-events migration note references the existing tracked migration issue rather than implying nothing is planned.
• Docs/comments only — no behaviour, entrypoint, storage, or error change.
• Do not duplicate the issues-1 "replace the placeholder README description" item; this issue targets the in-code struct/module doc strings specifically.

Suggested execution

• Fork the repo and create a branch
• git checkout -b docs/contracts-router-docstring-refresh
• Implement changes
  • Write code in: src/lib.rs — update the struct doc comment and the file-header note.
  • Write comprehensive tests in: src/lib.rs — no tests required; confirm cargo build/cargo test still pass.
  • Add documentation: ensure the struct doc and README.md describe the contract consistently.
  • Include NatSpec-style doc comments (///) in the rewritten struct doc, matching the existing style in lib.rs.
  • Validate security assumptions: accurate docs reduce auditor and integrator misunderstanding.
• Test and commit

Test and commit

• Run cargo fmt --all -- --check, cargo build, and cargo test.
• Confirm the word "placeholder" no longer describes the shipped router in the struct doc.
• Include a short before/after of the doc string in the PR description.

Example commit message

docs: replace placeholder router doc string with an accurate capability summary

Guidelines

• Minimum 95 percent test coverage for impacted modules.
• Clear, reviewer-focused documentation.
• Timeframe: 96 hours.

Community & contribution rewards

• 💬 Join the StableRoute community on Discord for questions, reviews, and faster merges: https://discord.gg/37aCpusvx
• ⭐ This is a GrantFox OSS / Official Campaign task and may be rewarded. When your PR is merged you'll be prompted to rate the project — if this issue and the maintainers helped you ship, we'd be grateful for a 5-star rating. Clear questions in Discord and tidy, well-tested PRs are the fastest path to a merge and a reward.

[gloskull]

Hi, I’d love to work on this issue. I have 4 years of experience across backend, frontend, full-stack, and smart contract development. I understand the task clearly and can deliver a clean, efficient, well-tested solution on time, with strong focus on code quality and maintainability. My PR will be submitted in under 10 hours.