Document the 33 public symbols that had no doc comment

[alaineid]

Adds a /// doc comment to each of the 33 public symbols that the five library modules declared without one, the ones PR #139's body listed at 4194e02. Comments only: every added line is a /// line, and no code, signature or access level changes. With it, every public symbol declared in OpenJevCore, OpenJevServer, OpenJevDiffusionGemma, OpenJevEncoders and OpenJevLetterReadout has a doc comment of its own (table below).

The comments

Sources/OpenJevDiffusionGemma/Model/VisionTower.swift, 31 symbols (added by #129):

Class	Symbols
ClippableLinear	callAsFunction(_:)
VisionRMSNorm	callAsFunction(_:)
VisionAttention	qProj, kProj, vProj, oProj, qNorm, kNorm, callAsFunction(_:positions:mask:)
VisionMLP	gateProj, upProj, downProj, callAsFunction(_:)
VisionBlock	selfAttention, mlp, inputLayerNorm, postAttentionLayerNorm, preFeedforwardLayerNorm, postFeedforwardLayerNorm, callAsFunction(_:positions:mask:)
VisionPatchEmbedder	inputProj, positionEmbeddingTable, callAsFunction(_:positions:padding:)
VisionModel	patchEmbedder, encoder, stdBias, stdScale
VisionEncoder	layers, callAsFunction(_:positions:mask:stages:)
MultimodalEmbedder	embeddingProjection, callAsFunction(_:)

• A property says what it holds and the checkpoint key it loads from, as the text model's properties do ("The key projection, k_proj." in Attention.swift). For example VisionModel.stdBias: "The shift the standardization subtracts from the soft tokens, std_bias, or nil when the configuration does not standardize."
• A callAsFunction says what it computes and returns. The four that take positions cite mlx-vlm's __call__ in vision.py, as the classes' comments cite vision.py, and list their parameters and result in the file's shape notation ([B, L, hidden], [B, C, H, W], [B, 1, L, L]), as Attention and DecoderLayer do. The four that take one array say it in a line or two, as DenseMLP does; VisionMLP's is "down_proj(gelu_approx(gate_proj(x)) * up_proj(x)), in x's shape, [..., hidden]."

Sources/OpenJevDiffusionGemma/Vision/VisionError.swift, description (#121): "The message.", the wording ServerSettingsError, JevK5ModelError and FixtureError, error structs of the same shape, use for the same description { message }.

Sources/OpenJevServer/ChatCompletionsRoute.swift, extension ChatCompletionsConfiguration (#136): "The generation settings that OPENJEV_GEN_* variables set, for POST /v1/chat/completions.", after BackendProvider.swift's "The engine settings that OPENJEV_* variables set, for DecisionBackendProvider." The route type is internal, so the comment names the route in code voice instead of linking it.

The vision comments rest on the code, the classes' comments, and mlx-vlm 0.6.15's models/gemma4/vision.py and gemma4.py, the version the file ports. Every key a property's comment names is part of the pinned checkpoint's tensor names (mlx-community/diffusiongemma-26B-A4B-it-4bit, its model.safetensors.index.json), under model.encoder.vision_tower. or model.encoder.embed_vision.. The clipping bounds ClippableLinear.callAsFunction(_:) names (input_min and the like) are not, since that checkpoint does not clip (use_clipped_linears is false). The shapes and ranges were checked in the code: VisionModel builds the mask as [B, 1, L, L] and the positions as int32 with x first, the position table's first slice is x's, and pixel_values arrive in [0, 1] (each byte times 1/255, no normalization), which _patchify maps to [-1, 1]. No symbol's purpose was unclear. No new comment contains a `` link.

Coverage, per module

Module	Public symbols declared in its sources	Without a doc comment at 4194e02	Without a doc comment on this branch (e8bd9b4)
OpenJevCore	735	0	0
OpenJevServer	88	1	0
OpenJevDiffusionGemma	603	32	0
OpenJevEncoders	300	0	0
OpenJevLetterReadout	96	0	0

A symbol counts when its accessLevel is public or open and its location.uri is under Sources/<Module>/. It has a doc comment when its docComment has a line with text and is its own: a comment copied from another module's protocol requirement (the graph marks it "module": "Swift", as for CustomStringConvertible.description's) does not count. Symbols with no location in the module's sources (synthesized and inherited members such as !=, hashValue, Actor's assertIsolated and Hummingbird's RequestContext defaults) need nothing and are left out. #137 (generation on the MLX backend) is still open, so its symbols are not counted.

OpenJevCore counts 735 where #139's table says 729. The 6 more are in OpenJevCore@Swift.symbols.json: the public pythonRepr extensions of Double and String in Errors/PythonRepr.swift (three extension blocks and three members), all documented. The next section says why that file was missed before.

How the counts were taken

For each module I ran the check docs/development.md names, swift package --allow-writing-to-directory "$DIR" generate-documentation --target <Module> --experimental-documentation-coverage --coverage-summary-level detailed --output-path "$DIR/<Module>.doccarchive", and read the symbol graphs in .build/out/Products/Debug/arm64/<Module>.symbolgraphs/. With this toolchain (Swift 6.4, SwiftPM's Swift Build backend), a graph file's modification time shows neither whether the run wrote it nor whether it is current:

• The run extracts a module's graphs only when it rebuilds the module, and then appears to write only the files whose content changed. On this branch, after the rebase, the run wrote no graph at all.
• The two files that looked stale were current. OpenJevCore@Swift.symbols.json (written at 10:02 today) and OpenJevServer@OpenJevCore.symbols.json (10:58) were byte for byte what a fresh extraction of 4194e02 gives. Moved aside, neither was re-created by a run over unchanged sources, and the 4194e02 run's DocC had read the 10:58 file: its warnings cite the comment of EngineConfiguration.init(_:), which only that file holds, and with the file moved aside they are gone.

So I also extracted each module's graphs, into an empty folder, from the module the run had just built: swift-symbolgraph-extract -minimum-access-level public -skip-inherited-docs -emit-extension-block-symbols, with the build's module and header search paths. On this branch, these graphs and the ones in .build hold the same symbols declared in the modules' sources, with the same doc comment text. At 4194e02 they matched too, apart from the extension-block files the run had not re-created. The table counts the extracted graphs.

DocC's own report agrees. In OpenJevDiffusionGemma's documentation-coverage.json, 36 entries under the nine classes of VisionTower.swift and VisionError had no abstract at 4194e02: the 32 above, plus VisionError's !=, localizedDescription and two "Implementations" groups, which no comment can document. On this branch only those 4 remain. In OpenJevServer's, the extension and its init(_:) both have an abstract.

The Coverage bullet in docs/development.md

#139 merged with a Copilot Autofix commit that turned the bullet into a rule, "Every public symbol needs a doc comment.", in place of the claim "Every public symbol declared in the five modules has a doc comment, and a new one needs one too." This pull request leaves docs/development.md alone (open #140 edits the bullet just above). With it merged the claim holds, and the table above is its evidence, if the bullet should say so again.

Checks

• make lint passes.
• The five single-target generate-documentation runs raise no warning in the three changed files; their warnings are the expected cross-module ones (Can't resolve 'OpenJevCore'). The new comments contain no links, and each - Parameters: list names exactly its function's parameters, so the Documentation workflow (every DocC warning an error, Sources/** in its paths) has nothing new to resolve. make docs was not run locally.
• The full swift test was not run: comments change no behavior, and CI runs the tests.
• Rebased onto main at 70d0126 (Say the DocC site has five modules, not four #139).

[Copilot]

Copilot review overview

🟢 Approval recommended

All added comments accurately describe the existing implementation and introduce no behavioral changes.

Review effort: Balanced
Findings: None

What changed in this PR

Adds missing API documentation across server, vision-error, and vision-tower public symbols without changing behavior.

Changes:

• Documents 31 vision-tower members and operations.
• Documents VisionError.description.
• Documents the chat-completions configuration extension.

File	Description
Sources/​OpenJevServer/​ChatCompletionsRoute.swift	Documents generation settings mapping.
Sources/​OpenJevDiffusionGemma/​Vision/​VisionError.swift	Documents the error description.
Sources/​OpenJevDiffusionGemma/​Model/​VisionTower.swift	Documents public vision-layer properties and calls.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.