[docs] feat: improve docstrings in seqlen_balancing.py (#1345)

[yurekami]

Summary

This PR improves the documentation quality of verl/utils/seqlen_balancing.py by adding comprehensive Google-style docstrings to core partitioning and utility functions.

Functions Improved

Function	Change
calculate_workload	Enhanced with mathematical formula (FLOPs ≈ 12h²s + 2hs²) and usage context
karmarkar_karp	Added algorithm description with Wikipedia reference
greedy_partition	Complete docstring explaining the bias mechanism for equal sizing
ceildiv	Added docstring with mathematical identity and usage examples
roundup_divisible	Added docstring with examples

Improvements Include

• Proper type hints on function signatures (list[int], torch.Tensor, return types)
• Detailed Args and Returns sections
• Usage examples for utility functions (ceildiv, roundup_divisible)
• Note sections for important implementation details
• See Also references for algorithm documentation

Context

The seqlen_balancing.py module implements workload balancing algorithms for distributed training:

• Karmarkar-Karp: Optimal multi-way partitioning using the Largest Differencing Method
• Greedy partitioning: Simpler alternative for workload distribution
• Utility functions: Support for micro-batch arrangement in dynamic batching

Test plan

• Python syntax verification passed
• CI tests should pass (documentation-only changes)

Contributes to #1345

🤖 Generated with Claude Code

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ vermouth1992
❌ yurekami
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[gemini-code-assist]

Code Review

This pull request significantly improves the documentation and type hints in verl/utils/seqlen_balancing.py, making the code more understandable and maintainable. The new Google-style docstrings are comprehensive and clear. I've found one issue where a type hint was broadened to include list[int] but the implementation only supports torch.Tensor, which could lead to a TypeError. I've suggested a fix to align the function signature and docstring with the implementation to prevent potential runtime errors.