Add `--ignore-private` and `--ignore-uncommented` flag support

[zwimer]

Just like there is an --ignore-magic flag, it would be nice if there were an --ignore-private and --ignore-uncommented flags.

Per the README for --ignore-magic:

Exclude dunder methods such as init, str, repr, eq, etc. from docstring generation. These are often implementation details that add noise rather than value to public documentation:

I'd say this statement can very much hold true for private or completely uncommented methods. For example, a small private method that is only briefly made to avoid code-deduplication by a printing function:

def _format(index: int, x: MyType) -> str:
    return f"{index}: {x}"

def print_stuff(stuff: Stuff) -> None:
    ...
    print(_format(1, x) + "\n" + _format(2, y))

In this case, adding a multi-line docstring would be unnecessary bloat.

Additionally, docstrings generated from completely uncommented might not be useful/helpful depending on why they are needed; A docstring with zero human comments might be useful for some program analyzing the system or metrics, but if they are being written for human eyes, since they are generated from the function signature, they might make it harder to read; i.e. "add noise rather than value to public documentation".

[FelixTheC]

@zwimer But this will then ignore all private functions. For a maybe more fine-grained way, I'm thinking about a decorator, something like @no_docs.

def _important_private(index: int, x: MyType) -> str:
    ...
    return some_val

@no_docs
def _format(index: int, x: MyType) -> str:
    return f"{index}: {x}"

def print_stuff(stuff: Stuff) -> None:
    ...
    print(_format(1, x) + "\n" + _format(2, y))

[zwimer]

I see the issue. Perhaps support ignoring undocumented as a flag, and for private (I still think you should support the flag for even if you discourage it), but for fine grain, use comments. These comments can be:

• For a single function: on the same line as the function declaration or right before it
• For all methods within a class: on the same line or right before it

Alternatively the two above, just logic that says 'if this comment is indented more than the line above, ignore until the next de-indented line that isn't part of a triple-quote string (if this makes the parsing easier for you)

• For the contents of a file: The first non-comment, non-docstring line

The comments could be like # docstring_gen: ignore[private] or # docstring_gen: ignore; this way a user could turn off generation for all private methods of a specific class without affecting public methods, for example. It should be noted that this comment should stop parsing at the each #. In case of something like # type: ignore # docstring_gen: ignore # noqa: F303 (as other linters require comments for things). Overall I'm thinking something similar to how ruff, mypy, or pylint work.

I think a decorator is not the way to go, however; as this is a code modification for documentation purposes which might have unintended effects.

[FelixTheC]

Nice idea, I will plan it and bring this feature in.

[FelixTheC]

@zwimer I need some clarification about the --ignore-uncommented. Do we still need this when we have # docstring: skip ? If you had time to create an example or two, this would be really helpful

[zwimer]

I think it would be nice; it'd avoid having to spam those comments everywhere if this tool is only being used for a small set of public API functions, for example.

[FelixTheC]

For --ignore-uncommented this means if no docstring is there you want to skip it for example this will be ignored

def some(a: int) -> str:
    ...

but this not

def some(a: int) -> str:
    """Lorem ipsum dolor samit"""
    ...

So you need some initial docstring to let the rest generated when this flag/config is set.
Is this correct so far?

I hope this doesn’t annoy you I only want to be sure that we both talk about the same expected behavior.

[zwimer]

Having my input valued is never annoying ;)

Personally, I'd at minimum like some flag that ignores functions that have no docstrings; if I don't give a function a docstring then chances are that it's not important enough to warrant one / adding one is just bloat.

The other method is also something that would be nice to have though. I think ruff has linters that verify that google-style docstring arg/return comments match the function if those comments exist. I.e. no complains if the function has a docstring but no Args comments. I think those are under their D style if you are curious. The important bit here obviously being this set of ignored functions is a superset of the first group. If you did this method, you might want to have this be an additional flag and also do the first separately.

All that said, if you just did the --ignore-uncommented with the first method, I think that's totally acceptable (as long 'uncommented' refers to only docstrings and not functions with # comments before/after the function declaration). Perhaps --ignore-undocumented would be preferable?

[FelixTheC]

I will be done by the end of the week. Only some testing is missing.

[FelixTheC]

@zwimer your requested Features are available withim the latest Version 2.2.0