~/bend-docscommunity

src/rules/style/doc.bend checks

raw source on the hub · import 0xd96f2ab40f5df4925c42e96d0ba857ff/src/rules/style/doc.bend as Doc

rule doc: every top-level def, type and law has a comment block right above it: one or more column-0 # lines with no blank line between them and the item. A block of bare # lines counts, though its text is empty; a line that starts inside a multi-line string literal is text, never a comment line. Helpers (dotted names like show.go) ride on their parent's doc, main needs none, PROOF.bend fills laws that LAWS.bend already documents, and a test (under tests/) is documented by its header and its check names.

7 imports
import Base
import ../../src.bend as Src
import ../../finding.bend as F
import ../../syntax/outline.bend as Outline
import ../../lazy/lazy.bend as Lazy
import ../../paths.bend as Paths
import ../../syntax/lex.bend as Lex

Definitions

def needs source · line 18 · raw

@kk:0xd96f2ab40f5df4925c42e96d0ba857ff/src/syntax/outline.ItemKind -> Bool

does an item of this kind need a comment?

def exempt source · line 30 · raw

@+name:String -> Bool

main, and helpers named x.go

def what source · line 34 · raw

@kk:0xd96f2ab40f5df4925c42e96d0ba857ff/src/syntax/outline.ItemKind -> String

an item's kind, for the message

def check.hash source · line 44 · raw

@lines:List<&2, String> -> @+nn:U32 -> Bool

is line nn of the lines a comment line (its first char #)?

def check.above source · line 55 · raw

@+lines:List<&2, String> -> @+nn:U32 -> Bool

is there a comment line right above line nn? A block of bare # lines counts, though its doc text is empty. An item's comment block always ends on the line right above it, so this test alone decides: the doc text, what the comments say, is never read

def check.go source · line 58 · raw

@items:List<&2, 0xd96f2ab40f5df4925c42e96d0ba857ff/src/syntax/outline.Item> -> @+path:String -> @+lines:List<&2, String> -> List<&2, 0xd96f2ab40f5df4925c42e96d0ba857ff/src/finding.Finding>

def lines.go source · line 68 · raw

@ls:List<&2, String> -> @+ins:List<&2, Bool> -> List<&2, String>

def lines source · line 77 · raw

@text:String -> @toks:List<&2, 0xd96f2ab40f5df4925c42e96d0ba857ff/src/syntax/lex.Tok> -> List<&2, String>

the lines of a source, each one that starts inside a string literal read as empty: it is text, never a comment line

def check source · line 81 · raw

@ss:0xd96f2ab40f5df4925c42e96d0ba857ff/src/src.Src -> List<&2, 0xd96f2ab40f5df4925c42e96d0ba857ff/src/finding.Finding>

the rule