Fixed docstring warnings and improvements

[hassaanfarooq01]

• Fixed mkdocs docstring warnings
• Added improvements docstring texts

[glenn-jocher]

@hassaanfarooq01 they're all fixed!!

[glenn-jocher]

@hassaanfarooq01 oh wait, this branch doesn't have the Docs checking action, so it's hard to tell haha. I think you're good to merge this into the CI branch, or vice versa, so you can tell if there are any warnings remaining.

[glenn-jocher]

@hassaanfarooq01 ok I just built locally. All the warnings are gone (good job)!

But there's one problem remaining. Every inlined return that does not have a variable name needs to be surrounded by parentheses in the docstrings, i.e.: here we need (bool) instead of just bool. Basically, types always need parentheses, otherwise mkdocstrings will not display them correctly (see screenshot) below:

def example_function(arg1: int, arg2: int) -> bool:
    """
    Example function that demonstrates Google-style docstrings.

    Args:
        arg1 (int): The first argument.
        arg2 (int): The second argument.

    Returns:
        (bool): True if successful, False otherwise.

    Examples:
        >>> result = example_function(1, 2)  # returns False
    """
    if arg1 == arg2:
        return True
    return False

Example screenshot showing problem

To fix this you would just put parenthesis around the return type: (requests.Response)

[hassaanfarooq01]

@hassaanfarooq01 ok I just built locally. All the warnings are gone (good job)!

But there's one problem remaining. Every inlined return that does not have a variable name needs to be surrounded by parentheses in the docstrings, i.e.: here we need (bool) instead of just bool. Basically, types always need parentheses, otherwise mkdocstrings will not display them correctly (see screenshot) below:

def example_function(arg1: int, arg2: int) -> bool:
    """
    Example function that demonstrates Google-style docstrings.

    Args:
        arg1 (int): The first argument.
        arg2 (int): The second argument.

    Returns:
        (bool): True if successful, False otherwise.

    Examples:
        >>> result = example_function(1, 2)  # returns False
    """
    if arg1 == arg2:
        return True
    return False

Example screenshot showing problem

To fix this you would just put parenthesis around the return type: `(requests.Response)`

mkdocs didn't raised warring for that therefore didn't get that. But yeah let me add it.

[glenn-jocher]

Yeah for this it doesn't raise warnings unfortunately, it's hard to check automatically so often times I just spot the tables built incorrectly in the published docs and then go fix them in the ultralytics docs.

Ok let me know when they're updated and I'll review again!

[glenn-jocher]

Needs parentheses

[glenn-jocher]

@hassaanfarooq01 there are number of corrections required here, this is very far from ready to merge.

Most importantly ALL usage of Optional requires brackets rather than parentheses.

PyCharm displays this clearly in your PR, you should probably use it when viewing your code.

[hassaanfarooq01]

@hassaanfarooq01 there are number of corrections required here, this is very far from ready to merge.

Most importantly ALL usage of Optional requires brackets rather than parentheses.

PyCharm displays this clearly in your PR, you should probably use it when viewing your code.

ohhh! it's stupid mistake. even wrote correct in docstring 🫣
yeah using vscode will jump to pycharm.

[glenn-jocher]

@hassaanfarooq01 ok let me know when it's ready, thanks!

[hassaanfarooq01]

@glenn-jocher I have reviewed the documentation thoroughly and implement the necessary changes to address issues with ui, with that also tried to add Notes and proper descriptions that will be helpful visually.

I know it should be done first time, but I was assuming to ui catch that automatically

[glenn-jocher]

@hassaanfarooq01 ok thanks, I will take a look today!

[glenn-jocher]

@hassaanfarooq01 looks much better! I think all the issues are resolved now. Nice work!