📖 2 min read (~ 400 words).

Single-line comments as descriptions

By the first-sentence convention, a single-line doc comment that ends in punctuation becomes the object’s title (on a model or the info block) or summary (on an operation); without trailing punctuation it is a description. That is the right default for most codebases, but some use single-line comments purely as prose — and then a stray period silently promotes the line to a title.

Options.SingleLineCommentAsDescription opts out of the promotion: a single-line comment is always a description, never a title / summary.

codescan.Run(&codescan.Options{
    Packages:                       []string{"./..."},
    ScanModels:                     true,
    SingleLineCommentAsDescription: true,
})

The witness pairs a model and an operation, each with a single-line comment that ends in a period:

// Gadget is a small device.
//
// swagger:model
type Gadget struct {
	Name string `json:"name"`
}

Full source: docs/examples/shaping/singleline/singleline.go

// swagger:route GET /gadgets gadgets listGadgets
//
// Lists every gadget in the catalog.
//
// responses:
//
//	200: gadgetsResponse

Full source: docs/examples/shaping/singleline/singleline.go

The same source, scanned both ways — the comment moves from title / summary to description uniformly:

Default — title / summary
{
  "modelDescription": "",
  "modelTitle": "Gadget is a small device.",
  "operationDescription": "",
  "operationSummary": "Lists every gadget in the catalog."
}

Full source: docs/examples/shaping/singleline/testdata/off.json

SingleLineCommentAsDescription: true
{
  "modelDescription": "Gadget is a small device.",
  "modelTitle": "",
  "operationDescription": "Lists every gadget in the catalog.",
  "operationSummary": ""
}

Full source: docs/examples/shaping/singleline/testdata/on.json

Info

Only the single-line case changes. A multi-line doc comment keeps the existing split — the first line (or the paragraph before the first blank line) stays the title, and the rest becomes the description. Reach for this option when your house style writes one-line prose descriptions and you don’t want them landing in title / summary; otherwise leave it off (the default) and write a two-line comment, or drop the trailing period, when you want a description.

What’s next