:docstring-no-summary on line-wrapped docstrings

[vemv]

Hi,

is this string supposed to be OK per :docstring-no-summary?

(ns bootstrap
  "Boring configuration stuff to ensure the virtual machine behaves the way we
  want."

https://github.com/bbatsov/clojure-style-guide/tree/b475d9e7e32c70b972f2d73e24ec790ea27bee22#docstring-summary says: Let the first line in the docstring be a complete, capitalized sentence which concisely describes the var in question.

It can be hard to meet that while also meeting e.g. a 80 columns limit. So, satisfying multiple linters at the same time might be hard here.

Perhaps clj-kondo could try detecting line-wrapped summaries. My tentative thinking would be:

Good

  "Boring configuration stuff to ensure the virtual machine behaves the way we
  want."

Also good

  "Boring configuration stuff to ensure the virtual machine behaves the way we
  want.

  Some extended description blah blah."

Bad

  "Boring configuration stuff to ensure the virtual machine behaves the way we
  want. Some extended description blah blah."

WDYT?

[vemv]

Another interesting specimen:

(defmacro check!
  "Evaluates `x` and throws an exception with `anomaly` as data
  if `x` does not evaluate to logical true."

For me this docstring is perfect as-is. But is the docstring a "summary"? It can be considered both a summary of what it does (briefly and in one sentence), and a docstring without a summary at all (because it makes no summary/content distinction at all; a small defn doesn't really need it).

I think that the right thing here is to be lenient in face of ambiguity, after all it's common to have clj-kondo as a hard CI check. Running this linter in a real-world codebase would raise hundreds of faults, which I don't find actually problematic to begin with. So it can be counterproductive to find most docstrings wrong, one would end up not enabling the linter at all. (Whereas I do see value in it)

[borkdude]

This has been discussed in Clojurians Slack:

https://clojurians.slack.com/archives/CHY97NXE2/p1640005869161800

The outcome of that discussion has been processed in linters.md:

https://github.com/clj-kondo/clj-kondo/blob/master/doc/linters.md#docstring-no-summary

[vemv]

Cheers. This quote seems to summarize the overall intent well:

I’m not surprised this linter triggers many warnings on “good” codebases. It’s pretty hard to summarize a function in a single short line.
Personally I really like the style since it forces clarity and it’s part of the clojure style guide but it’s definitely not for everyone. Which is the reason the linter is off by default.

In a way it admits that it won't be perceivedly useful by many, because it forces concision in a way that isn't particularly widespread.

I wonder one could add an opt-in option to make the linter more lenient as described in my OPs? I'd be willing to give it a shot.

n.b. I have no issue in keeping said option truly opt-in - I find it important to not disrupt the intent of those originally invested in :docstring-no-summary.

[borkdude]

I'll leave this up to @joodie as he authored this linter and I will accept what his take on it is.

[borkdude]

I actually found a good use case for the current behavior, apart from what @bbatsov has already stated about emacs's mini-buffer being 1 line high.

With babashka tasks it's possible to refer to functions and those functions can have long docstrings. Currently babashka displays the entire docstring in the bb tasks output:

$ bb tasks
The following tasks are available:

yarn-install               Installs and updates npm dependencies
watch:css:tailwind         Builds the css files with tailwindcss
build:css:tailwind         Builds the css files with tailwindcss
build:cljs                 Builds production JS
build:front-end            Builds all front-end assets
cached-browser-release     build/upload or download cached assets
foo:upload                Copies local foo transformed data structures to bar.
  Intended to be used after `dude` script and
  `...` rich comment have been run locally and the
  resulting data structures (as Nippy) are ready for their new life in
  the cloud.
dev:clj                    Starts the Clojure-only dev system
dev                        Starts the full dev system and the tailwind css watcher

I might change that to only display the first line and this linter would help writing in that style.

/cc @daveliepmann