How do you use clj-kondo in ci process? Before testing or after? How do you invalidate the ci from any kondo condition?

Hm, the idea behind :docstring-no-summary does not work for docstrings like

"Puts a diagnostic context value `v` as identified with the key `k`
   into the current thread's diagnostic context map.
   Returns a Closeable object who can remove key when close is called.
   The `k` cannot be null.
   If the `v` is null then nothing is put and noop Closeable returned."

@serioga makes sense. I'm open to receive improvements either from you, @joost-diepenmaat or anyone else.

I guess it's a question to @joost-diepenmaat about concept of this linter 🙂 I like an idea in general but current implementation is not really useful for my codebase.

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.

@joost-diepenmaat I think the issue is that not all sentences are on a first line because of how docstrings are formatted.

"Puts a diagnostic context value `v` as identified with the key `k`
   into the current thread's diagnostic context map.

The problem is that the line is too long.

At least that’s my interpretation. I would go with max -80 characters for a summary

It’s intended that summaries fit on a single line on screen.

That's not really in line with how most clojure code looks and how emacs formats things. I guess this linter is pretty useless for most people if we keep it like this.

For me the reference how to write docstrings is clojure.core. But most docstrings in clojure core will not pass this linter 🙂

We can take a look at what cider does with apropos. That lists the first sentence (not line)

Would still recommend a short first sentence but fine by me to lift te restriction on newlines.

I’m offline for a bit. Will be back later

I guess it depends on the idea of "summary". The docstring posted by @serioga doesn't really have a summary, by the definition of the linter (currently).

but I guess the idea was inspired by https://guide.clojure.style/#docstring-summary

so we should probably implement what is referred to in the style guide by @bozhidar

which is kind of ambigious

or not, I don't know.

I'll leave it up to you to decide

Well, for me I see a useful linter that docstring starts from uppercase letter and ends with period, ignoring newlines.

the styleguide recommends placing the summary on a single line it seems. The next sentence should not begin on the same line for example.

makes sense

ok, let's leave it like this then - sorry to bother you @joost-diepenmaat - a link to the style guide in linters.md would be good

@borkdude The idea is simple - each docstring should start with a one-line sentence. This minimizes the work tools have to do to extract some meaningful summary of what a var does (and as a bonus - it plays great with the Emacs minibuffer, that happens to have a height of 1 line).

ok, this is the conclusive info we needed. we just need to update linters.md with it then

Even more importantly - it's nice for humans to start with a short and clear summary and then expand on it if needed.

thanks!

You're welcome!