autogen icon indicating copy to clipboard operation
autogen copied to clipboard

Published 20 hours ago • verified publisher icon microsoft

[Issue]: Improve consistency of doc strings across modules

Open gagb opened this issue 1 year ago • 10 comments

Describe the issue

Doc strings across all files lack consistency, presumably because different authors are using different conventions (including me). Eg, these are PEP 257 guidelines for multi-line doc strings:

image

It's easy to spot even the violations of the first para. For example:

  • RetrieveUserProxyAgent does not have the first single line. https://github.com/microsoft/autogen/blob/ee17f19d30a20c1747f4828c8f86faa296c2ca1a/autogen/agentchat/contrib/retrieve_user_proxy_agent.py#L64-L76

  • initiate_chats uses extra indents that cause it to not render properly in vscode documentation pop outs. https://github.com/microsoft/autogen/blob/ee17f19d30a20c1747f4828c8f86faa296c2ca1a/autogen/agentchat/chat.py#L134-L143

cc. @ekzhu @jackgerrits

gagb avatar Mar 18 '24 07:03 gagb

Additionally, I think we should settle on Google style docstrings. There is great support for them and they are (in my opinion) the easiest to read. A large amount of the codebase already uses this style too. So it's really just making this fact explicit.

  • https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html
  • https://gist.github.com/redlotus/3bc387c2591e3e908c9b63b97b11d24e
  • https://google.github.io/styleguide/pyguide.html#383-functions-and-methods

jackgerrits avatar Mar 18 '24 13:03 jackgerrits

Additionally, I think we should settle on Google style docstrings.

Agreed.

gagb avatar Mar 18 '24 17:03 gagb

Is this issue still open. Can I have the opportunity to work on this issue.

sharsha315 avatar Mar 20 '24 09:03 sharsha315

Is this issue still open. Can I have the opportunity to work on this issue.

@sharsha315 Yes, please go ahead.

RohitRathore1 avatar Mar 20 '24 16:03 RohitRathore1

Hi, a little help, Please. I made the necessary changes, formatted the docstrings, but when I make a commit I am getting an error and the git commit is getting failed. I have enclosed the snapshots of the errors. commit_error_1 commit_error_2 commit_error_3

sharsha315 avatar Mar 22 '24 08:03 sharsha315

Hi @RohitRathore1, a little help here. Please, help me with this above error, I am not able to go on further.

sharsha315 avatar Mar 23 '24 10:03 sharsha315

This was fixed in main by https://github.com/microsoft/autogen/commit/fafc29eeef56221fe2004ef83aa1a9d11578c069, please make sure you've updated to latest

jackgerrits avatar Mar 23 '24 13:03 jackgerrits

This was fixed in main by fafc29e, please make sure you've updated to latest

Thank you for the quick response. It's working now.

sharsha315 avatar Mar 23 '24 14:03 sharsha315

Hi @RohitRathore1, I have submitted the PR. Please, review the PR and provide feedback. Thank you.

sharsha315 avatar Mar 23 '24 14:03 sharsha315

@sharsha315 Thanks for your PR. Please read the CLA & if you are agree with it then you can comment @microsoft-github-policy-service agree in the same PR.

RohitRathore1 avatar Mar 23 '24 17:03 RohitRathore1