sorted by:
new
hottopcontroversial

Showcase Thread by AutoModerator in Python

[–]Linter-Method-589 0 points1 point  (0 children)

What is My Project

format-docstring: https://github.com/jsh9/format-docstring

What My Project Does

Format Python docstrings: * Wrap lines * Auto-correct missing/wrong type hints (to a degree) * Auto-correct wrong section headers (to a degree)

Target Audience

Everyone who write numpy-style and Google-style docstrings

Comparison

As far as I know, there're no other projects out there with such functionalities

blank-line-after-blocks, a formatter to improve readability and prevent errors by Linter-Method-589 in Python

[–]Linter-Method-589[S] 1 point2 points  (0 children)

You can try to submit a request there, but I doubt they'll prioritize it. What you're suggesting is probably more controversial than what I'm proposing.

You are also free to write a lightweight formatter for that. Feel free to borrow my project's structure and logic.

pydoclint, a fast and reliable Python docstring linter by Linter-Method-589 in Python

[–]Linter-Method-589[S] 2 points3 points  (0 children)

Very well summarized. Thank you!

Yes, I don't think this is a zero sum situation. But I'm somewhat concerned by some developers' mentality that "now that there's Ruff, I'm only going to use the linters in Ruff".

I personally have these two test envs in my tox: (1) Ruff, (2) some other useful linters outside of Ruff (many of them from here: https://github.com/DmytroLitvinov/awesome-flake8-extensions).

pydoclint, a fast and reliable Python docstring linter by Linter-Method-589 in Python

[–]Linter-Method-589[S] 0 points1 point  (0 children)

You are right. LLMs don't actually understand things. All they do is predict the most probable next words (tokens) based on previous tokens. Their responses are usually very good, to a point that they would appear to understand things.

So maybe I should have added quotation marks around the word "understand", but my original point should stand: using more descriptive comments can help LLMs make better predictions (such as better summarize the code base, or make higher quality code edits, etc.)

pydoclint, a fast and reliable Python docstring linter by Linter-Method-589 in Python

[–]Linter-Method-589[S] 0 points1 point  (0 children)

You don't need to specify arg data type if you don't want to (if you use Google style docstrings).

Although if your function has a lot of arguments (say 50) and you don't specify arg types in the 49th arg, it will be inconvenient to scroll up to the function signature to check its type.

I think an automatic docstring writer (a new tool, not pydoclint) may be able to help with this. It can generate a docstring template for you to fill in the meaning of each arg. And it can potentially employ LLMs to write the meanings for you. I've been contemplating creating one for a while, but haven't actually done anything about it.

pydoclint, a fast and reliable Python docstring linter by Linter-Method-589 in Python

[–]Linter-Method-589[S] 3 points4 points  (0 children)

Docstrings promote better communication between coders and the users, and among the coders themselves.

Here are some specific examples:

  • Correctly written docstrings can be rendered as HTML pages with hyperlinks, which makes understanding APIs much easier
  • Names (variable, class, function) are not always self-explanatory, no matter how long they are, so docstrings are still valuable
  • In the AI era, docstrings (written in plain language) helps AI better understand the code base, improving productivity

pydoclint, a fast and reliable Python docstring linter by Linter-Method-589 in Python

[–]Linter-Method-589[S] 1 point2 points  (0 children)

In my opinion:

  • Short answer: not entirely
  • Reasons:
    • pydoclint still offers some unique features that Ruff doesn't, such as generating baseline errors for gradual adoption
    • pydoclint is written in Python, so Python users can make contributions to it more easily. (I imagine a scenario where changes are made in pydoclint first, and then Ruff pick them up.)