docs: update mcore optimizer docstrings to google style

[Akshat8510]

Description

This PR updates and standardizes the docstrings for the megatron/core/optimizer module to follow the Google Style Guide. This is part of the documentation overhaul tracked in issue #2653.

Changes

• Updated optimizer.py, distrib_optimizer.py, grad_scaler.py, and clip_grads.py with structured Args, Returns, and Attributes blocks.
• Formatted OptimizerConfig dataclass attributes for better compatibility with auto-generated API guides.
• Refined technical descriptions and updated documentation references to use relative paths.

Files Updated:

• megatron/core/optimizer/clip_grads.py
• megatron/core/optimizer/distrib_optimizer.py
• megatron/core/optimizer/grad_scaler.py
• megatron/core/optimizer/optimizer.py
• megatron/core/optimizer/optimizer_config.py
• megatron/core/optimizer/qk_clip.py

Mentions: @Phlip79 @sbhavani

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[Akshat8510]

Hi @Phlip79, I have submitted a PR for the optimizer and clip_grads modules as part of this docstring update.

[Phlip79]

Thank you Akshat! Could you please ensure that your changes do not reduce verbosity?

[Akshat8510]

Thank you for the feedback, @Phlip79! I will do a thorough pass over all the changed files to ensure that all technical details and explanations from the original comments are preserved within the new Google Style format. I'll update the PR shortly.

[Akshat8510]

Hi @Phlip79, I have updated the docstrings across all 6 files to restore the original technical verbosity and detailed explanations while maintaining the Google Style structure. This includes restoring the core mapping logic in distrib_optimizer.py, the FSDP/filtering details in clip_grads.py, and the in-place modification warnings. Thank you for the feedback!

[Akshat8510]

Hi @Phlip79 and @chtruong814, I wanted to follow up on this PR. I have addressed the feedback regarding technical verbosity across all 6 files.

[Akshat8510]

I noticed the needs-follow-up label is still active, please let me know if there are any further changes required on my end to clear this and move toward a merge. Thank you!

[Akshat8510]

Hi @Phlip79 @chtruong814, I've squashed the commits and restored the technical verbosity as requested. Should I update the branch whenever it is out-of-date with main, or only if merge conflicts occur?

[Akshat8510]

Hi @Phlip79 and @chtruong814, it's been two weeks since I restored the technical verbosity and squashed the history. The PR is ready for a final look.

[Akshat8510]

Could you please trigger the internal tests (approve the workflow) so we can see if any further adjustments are needed? Thank you!

[Akshat8510]

Hi @Phlip79 and @chtruong814,
I noticed the needs follow-up label was added again. Could you please let me know what specific changes are required from my side? I’m happy to address any feedback to help move this forward. Thank you!

[Akshat8510]

Hi @chtruong814,
I noticed the needs follow-up label was added again. Could you please let me know what specific changes are required from my side? I’m happy to address any feedback to help move this forward. Thank you!

[Akshat8510]

it's been more than 3 weeks since I restored the technical verbosity and squashed the history. The PR is ready for a final look.

[Akshat8510]

Hi @chtruong814, I've addressed all the requested changes, restored the technical verbosity

[Akshat8510]

The PR is ready for review.
Looking forward to your feedback. Thanks!

[Akshat8510]

hi @chtruong814 , thank you for removing the follow up label. can you pls review my PR ? It was about improving standardizes the docstrings for the megatron/core/optimizer module to follow the Google Style Guide.

[Akshat8510]

Hi @chtruong814, I noticed the needs-follow-up label was added again.
Could you please let me know if there are any remaining changes required from my side?

Happy to address them. Thanks!

[Akshat8510]

Hi @chtruong814, I noticed the needs-follow-up label was added again.
Could you please let me know if there are any remaining changes required from my side?

Happy to address them. Thanks!

[Akshat8510]

Thank you @chtruong814 for removing follow up label, pls review this PR

[Akshat8510]

Hi @chtruong814, I noticed the needs-follow-up label was added again.
Could you please let me know if there are any remaining changes required from my side?

Happy to address them. Thanks!

[Akshat8510]

Thank you @chtruong814 for removing follow up label, pls review this PR

[Phlip79]

Thank you for taking the time to create this PR. I have a few nits.

Apologies it took so long to review, this PR went completely unnoticed because the "Expert Review" label was not added.

We are actually changing the review process moving forward to make the process more clear in #3659.

[Phlip79]

/ok to test b0aa307

[Akshat8510]

Hi @Phlip79, I have squashed the branch into a single clean commit and restored the technical details in distrib_optimizer.py and optimizer_config.py as requested. I've also ensured that all docstrings follow the Google Style Guide. This PR is ready for final review. Thank you!

[Akshat8510]

And I like the new PR review change mention in 3659 with this, PR review become more smoother