parsers

type ParsedPathContent struct {
	Method, Path, ID string
	Tags             []string
	Remaining        *ast.CommentGroup

	// Pos is the position of the matched route/operation annotation line (the comment group's start).
	//
	// Used to anchor diagnostics such as the stripped-regex warning.
	// Pos is the (coarse) source position of the matched route/operation annotation line — the comment's Slash.
	//
	// Used as:
	// - anchor for diagnostics, such as the stripped-regex warning.
	// - the cross-ref anchor for the /paths/{path}/{method} node. Invalid when no annotation matched.
	Pos token.Pos

	// UnparsedPos / UnparsedLine record a line recognisable as a path annotation — keyword, method and a path — that
	// did not parse as one.
	//
	// Both are zero unless that happened.
	//
	// Nothing downstream can recover this: a `swagger:route` that fails its regex leaves no trace and reads as ordinary
	// prose, so the route goes missing with no diagnostic anywhere.
	// Capturing it here is what lets the caller say so — but only when the group produced no route at all, since a group
	// may legitimately hold both a good annotation and prose that resembles one.
	UnparsedPos  token.Pos
	UnparsedLine string

	// StrippedParams names the path parameters whose inline regex constraint (gorilla/chi style, e.g. `{id:[0-9]+}`) was
	// stripped to the bare `{id}` template form.
	//
	// OpenAPI 2.0 path templating supports only RFC 6570 URI Template Level-1 expansion (simple `{var}` substitution), so
	// any `:regex` constraint is dropped and surfaced to the author by the route/operation builder.
	StrippedParams []string
}