[community] Improving docstrings and type hints

@yiyixuxu

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.

@a-r-r-o-w

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 🙂

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)

I'll take up some of these.

@charchit7

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

@yijun-lee

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.

@charchit7

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

@yijun-lee

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

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.

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

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!

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) ?

@a-r-r-o-w

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

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 :)

Improve docstrings and type hints in scheduling_ddim.py

Improve docstrings and type hints in scheduling_amused.py

Hi 👋

I'm working on improving the docstrings and type hints for all scheduler files. I've already opened two PRs:

Improve docstrings and type hints in scheduling_ddim.py #12622 - scheduling_ddim.py ✅
Improve docstrings and type hints in scheduling_amused.py #12623 - scheduling_amused.py ✅

I plan to continue with the other schedulers in the src/diffusers/schedulers/ directory. I'll submit one PR per file as recommended.

Let me know if there are any specific schedulers you'd like me to prioritize or if you have any feedback on my approach. Thanks!

Improve docstrings and type hints in scheduling_amused.py (#12623)

Improve docstrings and type hints in scheduling_ddim.py

Improve docstrings and type hints in scheduling_ddim.py (huggingface#…

@stevhliu

Hi @stevhliu ! Sorry for the long silence since my last contribution back in February. I had a baby, so I've been quite busy 🙂 Will start submitting PRs again soon!

Navigation Menu

Repository navigation

[community] Improving docstrings and type hints #9567

11 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[community] Improving docstrings and type hints #9567

Description

Activity

whtssub commented on Oct 2, 2024

a-r-r-o-w commented on Oct 2, 2024

charchit7 commented on Oct 2, 2024

yijun-lee commented on Oct 4, 2024

charchit7 commented on Oct 4, 2024

yijun-lee commented on Oct 4, 2024

charchit7 commented on Oct 4, 2024

Divyam01325 commented on Oct 4, 2024

a-r-r-o-w commented on Oct 4, 2024

jeongiin commented on Oct 5, 2024

ahnjj commented on Oct 5, 2024

Ashutoshjangam commented on Oct 5, 2024

11 remaining items

RogerSinghChugh commented on Oct 20, 2024

delmalih commented on Nov 10, 2025

delmalih commented on Jul 7, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions