[community] Improving docstrings and type hints

[a-r-r-o-w]

There are many instances in the codebase where our docstring/typing convention is not followed. We'd like to work on improving this with your help!

Our convention looks like:

def function_name(parameter_1: Union[str, List[str]], parameter_2: Optional[int] = None, parameter_3: float = 42.0) -> Civilization:
    r"""
    Function that creates a simulation.

    Args:
        parameter_1 (`str` or `List[str]`):
            Description of game level.
        parameter_2 (`int`, *optional*):
            Kardashev scale of civilization.
        parameter_3 (`float`, defaults to `42.0`):
            Difficulty scale.

    Returns:
        [`~simulations.objects.Civilization`]
            A civilization simulation with provided initialization parameters.
    """

Some examples that don't follow the docstring convention are:

• this: missing explanations
• this: does not contain mixin-related documentation whereas as this does
• this: function explanation after "Args", but should be before
• this: same reason as above
• this: incorrect indentation

There are also many places where docstrings are completely missing or inadequately explained. If you feel something needs an improvement, you can open a PR with your suggestions too! Additionally, type hints are not appropriate/correctly used at many occurrences and mismatch the accompanying docstrings - these could use an improvement too!

Please limit your PRs to changes to a single file in each PR. Changes must be only related to docstrings/type hints. Feel free to ping either @yiyixuxu, @stevhliu or me for reviews.

[SubhasmitaSw]

Hi @a-r-r-o-w I'd like to take this up, please let me know if there are any other prerequisites I should be aware of before submitting a PR against this issue 🙂

[a-r-r-o-w]

Not prerequisites I can think of off the top of my head. Just that the PRs should be limited in scope as mentioned. You can maybe look at the Diffusers contribution guide (and philosophy, if you're interested)

[charchit7]

I'll take up some of these.

[yijun-lee]

I’m also interested in this work. Could you let me know about the current progress? @SubhasmitaSw @charchit7

[charchit7]

Hey @yijun-lee, I've been caught up with some work, unfortunately, but I’ll work on this over the weekend or later today. If you want to get started on any of these tasks, feel free to go ahead and let us know, so we can pick up whatever is left.

[yijun-lee]

Oh, actually, I think I’ll be starting this weekend as well. If we proceed separately, it would be good to inform each other through comments or other means. Have a good day :) @charchit7

[charchit7]

Sure, @yijun-lee, that works!
you too :)

[DTG2005]

Hello there guys, I'd also like to contribute in this issue. I'm sorry I didn't really drop in a message here yet but I hope this PR helps push things forward! A g'day to all.

[a-r-r-o-w]

Feel free to take up as many files as you want (one file per PR however)! The ones mentioned in the issue description are just a few examples, but there are probably hundreds of files that could use improvements. Please keep them coming, thanks

[jeongiin]

Hello! I'm also following this issue with interest. I’ve submitted my first PR, so please let me know if there are any mistakes! Have a great day!

[ahnjj]

Hello! Thanks for holding interesting issue! I'm fully circled for this new work ! 🙆🏻‍♀️ 🙆🏻‍♀️
I also have opened my PR, please let me know if I missed something !

• Q. which should I prioritize modern python docstring conventions or unity of that file (e.g. expression) ?

[Ashutoshjangam]

@a-r-r-o-w hi, i wank to work on it

[Jwaminju]

Hello colleagues,
I'm also interested into this issues. I made a first PR related to this issue.
Since there are lots of docstrings to update, I'm also interested into list up missing docstring files if I have time :)
Thank you in advance for your time and guidance!

[mreraser]

Hello everyone! 😊
I'm also interested in this issue and have made some updates to the docstrings in src/diffusers/training_utils.py. I would love to get your feedback on my changes!

I’m excited to contribute and be part of this discussion. Thank you in advance for your time and guidance 🤗

[RogerSinghChugh]

Hi I would love to be of help here.
I have made some additions to the docstrings in src/diffusers/training_utils.py.
Would love to get your feedback on the PR :)