Consolidate the jsonpull comments

Comments were 25% of the added lines, and the ownership model was spelled
out in five places. Collect it into one block at the top of jsonpull.h and
point at it from the rest, cutting the ratio to 14% and the total by about
200 lines.

Removed the duplicate explanations of the deleter dispatch, of what detach
does to the back-pointers, and of "json_read returns intermediate
containers, do not free them". Trimmed the comments that argued for a
choice rather than described the code -- the reserve(2) / reserve(4)
rationales, the string-buffer copy, the pmtiles check ordering -- to a line
each, and shortened the test preambles, keeping the parts that say why a
test is shaped the way it is.

No code changes; the test suite is unchanged in both configurations.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017KNxyHKasyWrWcvre2yK4r
This commit is contained in:
Claude
2026-08-14 04:17:06 +00:00
parent e3de1f6731
commit 4ab8c66b86
8 changed files with 120 additions and 321 deletions
+4 -9
View File
@@ -147,15 +147,10 @@ serial_feature parse_feature(json_pull_ptr &jp, int z, unsigned x, unsigned y, s
serial_feature sf;
while (1) {
// json_read returns each token as the parser produces it, including
// intermediate (still incomplete) container nodes. We must NOT free
// these intermediates here: they belong to the larger feature hash
// still being assembled, and freeing them would splice them out of
// the parent and corrupt the in-progress tree. So the `continue`
// paths below all leave `j` alone; `j` is only freed once it is a
// complete Feature hash -- either just before returning it, or at
// the bottom of the loop if its geometry turned out to be empty --
// or as `jp->root` when the stream ends.
// json_read also returns the intermediate containers of a feature
// still being assembled, so the `continue` paths leave `j` alone;
// freeing one would splice it out of its parent. `j` is only freed
// once it is a complete Feature.
json_object *j = json_read(jp);
if (j == nullptr) {
if (jp->error != nullptr) {