docs: fix the tcpclient package comment typo and exported API documentation #13

New issue

Closed

opened 2026-07-21 17:20:23 +02:00 by heiko · 1 comment

heiko commented

2026-07-21 17:20:23 +02:00

Owner

Problem

internal/tsp-tcp/tcp.go begins with:

// Package tcpclient implements the tspclient.Timerstamper interface

Timerstamper is a typo for Timestamper. Additional comments call the implementation RFC 3161 plain TCP even though the current wire behavior sends raw DER, half-closes, and reads raw DER rather than implementing RFC 3161 section 3.3 length/flag framing.

Checklist: #15 (accurate documentation for exported packages/elements).

Proposed fix

Correct the interface name.
Document the actual raw-DER/EOF wire behavior and its FreeTSA compatibility history.
Do not label it standards-compliant RFC 3161 socket framing unless length/flag framing is implemented.
Keep README, CLAUDE.md, package docs, tests, and manual pages consistent.

Acceptance criteria

Package and exported API comments are typo-free and match actual behavior.
go doc does not claim unsupported RFC 3161 TCP framing.
Documentation clearly distinguishes the RFC 3161 payload from its transport framing.

Reviewed against 948b7a9 on master (Go 1.26.2).

## Problem `internal/tsp-tcp/tcp.go` begins with: ```go // Package tcpclient implements the tspclient.Timerstamper interface ``` `Timerstamper` is a typo for `Timestamper`. Additional comments call the implementation RFC 3161 plain TCP even though the current wire behavior sends raw DER, half-closes, and reads raw DER rather than implementing RFC 3161 section 3.3 length/flag framing. Checklist: #15 (accurate documentation for exported packages/elements). ## Proposed fix - Correct the interface name. - Document the actual raw-DER/EOF wire behavior and its FreeTSA compatibility history. - Do not label it standards-compliant RFC 3161 socket framing unless length/flag framing is implemented. - Keep README, `CLAUDE.md`, package docs, tests, and manual pages consistent. ## Acceptance criteria - Package and exported API comments are typo-free and match actual behavior. - `go doc` does not claim unsupported RFC 3161 TCP framing. - Documentation clearly distinguishes the RFC 3161 payload from its transport framing. Reviewed against `948b7a9` on `master` (Go 1.26.2).

heiko commented

2026-07-21 23:07:56 +02:00

Author

Owner

Package/API documentation now accurately describes the raw-DER/EOF TCP transport and correct interface name.

Closing commit: b5c194322a89

Package/API documentation now accurately describes the raw-DER/EOF TCP transport and correct interface name. Closing commit: [`b5c194322a89`](https://forgejo.schlittermann.de/heiko/mail-seal/commit/b5c194322a8904230e4771c9aa55d20065f30913)

heiko closed this issue

2026-07-21 23:07:57 +02:00

heiko referenced this issue from a commit

2026-07-22 11:18:25 +02:00

test(tsp-tcp): cover at-limit accept, short write, full endpoint table; fix docs