def quality_check_docstring()

in src/doc_builder/autodoc.py [0:0]

• 31 lines of code
• 15 McCabe index (conditional complexity)

def quality_check_docstring(docstring, object_name=None):
    """
    Check if a docstring is not going to generate a common error on moon-landing, by asserting it does not have:

    - an empty Return block
    - two (or more) Return blocks
    - a code sample not properly closed.

    This function only returns an error message and does not raise an exception, as we will raise one single exception
    with all the problems at the end.

    Args:
        docstring (`str`): The docstring to check.
        obejct_name (`str`, *optional*): The name of the object being documented.
            Will be added to the error message if passed.

    Returns:
        Optional `str`: Returns `None` if the docstring is correct and an error message otherwise.
    """

    lines = docstring.split("\n")
    in_code = False
    code_indent = 0
    return_blocks = 0
    error_message = ""

    for idx, line in enumerate(lines):
        if not in_code and _re_start_code_block.search(line) is not None:
            in_code = True
            code_indent = find_indent(line)
        elif in_code and line.rstrip() == " " * code_indent + "```":
            in_code = False
        elif _re_returns_block.search(line) is not None:
            next_line_idx = idx + 1
            while next_line_idx < len(lines) and is_empty_line(lines[next_line_idx]):
                next_line_idx += 1
            if next_line_idx >= len(lines) or find_indent(lines[next_line_idx]) <= find_indent(line):
                error_message += "- The return block is empty.\n"
            else:
                return_blocks += 1

    if in_code:
        error_message += "- A code block has been opened but is not closed.\n"
    if return_blocks >= 2:
        error_message += f"- There are {return_blocks} Returns block. Only one max is supported.\n"

    if len(error_message) == 0:
        return

    if object_name is not None:
        error_message = (
            f"The docstring of {object_name} comports the following issue(s) and needs fixing:\n" + error_message
        )

    return error_message