Check for summary lines before or after signature

[goerz]

Just throwing this out there, from "Docstrings: Imperative or indicative mood" (comment):

I would like a docstring linter to be able to check for summary lines, either after the signature (as the Julia manual recommends), or before the signature (my personal style).

For the latter, it would be extra nice to be able to enforce that the summary is written in the imperative style, but the text from the codeblock onwards is written in the descriptive style.

[tecosaur]

Good news! I'm already doing this :wink:

The current set of rules checks that:

• There's a signature
• There's a summary line after the signature
• The summary line starts with a capital letter and ends in punctuation
• The summary line uses imperatively voiced verbs
• The summary line is no longer than 96 characters (I'm up for tweaking this limit)

[Datseris]

It is often the case that the summary statement of a function needs more than one sentence. Many of my docstrings would fail the last bullet point simply because it is not possible to articulate clearly a compelx function ina single sentence. What do we do in such a scenario?

(my summary sentences are at the moment always after the signature code block)

[tecosaur]

I'd actually argue that if the (high-level) purpose of a function can't be articulated in a single line, that function shouldn't exist 😛

[tecosaur]

As someone who's had plenty of issues with length-limited summary lines though (in Emacs, where the limit is 80), I most often find the real issue is that I've tried to squeeze too much detail into the summary.