Skip to content

doc(stela): document arrays, the visitor and the writer - #64

Merged
kniz merged 2 commits into
mainfrom
doc/stela-visitor-writer-arrays
Sep 6, 2026
Merged

kniz merged 2 commits into
mainfrom
doc/stela-visitor-writer-arrays

Conversation

@kniz

@kniz kniz commented Sep 4, 2026 •

Copy link
Copy Markdown
Member

aj-architecture-stela.md was frozen at the state before the visitor was introduced (2026-08-13), so none of the APIs added to stela since then were documented. This fills that gap, along with the dependency pin bump and the broken-example fixes it requires.

This is a pair with PR #63 (doxygen INPUT path fix). Without #63 the @ref by::arrStela-style links in this doc won't be generated at all, so please merge #63 first.

What was filled in

The existing doc only had stela / valStela / verStela / nulStela. The additions are:

Item Section
strStela — why the string tag type exists separately (the writer needs a type to know when to add quotes) ### strStela 클래스 - 문자열 값
arrStela — {a, b, c} syntax, sub(index) access, the "0000" element-name rule and the IDX_WIDTH limit ### arrStela 클래스 - 배열
stelaVisitor — the onVisit / onTraverse / onLeave 3 phases, per-type overloads with super chain-up, work() ### stelaVisitor 클래스 - 트리 순회
accept() + VISIT() / DEF_VISIT() / visitee.inl — the three places to touch when adding a new subtype ### accept와 VISIT 매크로
stelaVisitInfo — name / parent / index / len / depth ### stelaVisitInfo 클래스 - 순회 문맥
stelaWriter — write(), writeFile(), what the canonical form preserves and drops ### stelaWriter 클래스
Tree-manipulation API — sub(index), add(), del(), has(), len(), begin()/end() paragraph added inside ### stela 클래스

That add() overwrites a child of the same name (f6c07ba) and that sub(name) does not create an empty child on failure (4260388) both affect caller code, so they are called out explicitly in the text.

The two class diagrams were also corrected to the real inheritance (strStela/verStela → valStela, arrStela/nulStela → stela), and the overview diagram now includes the Visitor Package.

Changes bundled in

stela pin bump (3d39295 → ade6414): module/core/CMakeLists.txt. The old pin was 08-21, which does not include array support (280416f, 09-02). Without bumping the pin, the arrStela this doc describes isn't actually vendored, so the @refs break again.

verStela example fix: the existing example was tagged verified but did not compile.

stela& root = stelaParser().parse(script);   // parse() returns tstr<stela>
stela& root = ...; root->sub("package");     // -> on a reference

The stela example just above it was written correctly, so the two contradicted each other. The range comparison also had only a "can be checked" comment with no actual code, so it was filled in to use the comparison operators that are actually defined.

Verification

The reference commit for the doc is stela ade6414 (origin/main tip), and all 6 C++ examples were compiled and run against that commit. The output shown in the writer section was confirmed to match the actual write() result byte-for-byte (down to children being re-sorted alphabetically and the later-added author coming first).

Rendering was also checked by running DoxyReference-ko with #63's INPUT fix applied. All newly added sections appear, and references like by::arrStela, by::strStela, by::stelaWriter, by::stelaVisitInfo link correctly to their class pages.

Known issues

The 3 @ref by::stelaVisitor links don't resolve and render as plain text. stelaVisitor uses an X-macro pattern that #includes visitee.inl inside the class body, which Doxygen can't pick up as a class. byeol core's visitor has no class page for the same reason, so this predates this PR; fixing it would require touching the source structure, so it was left as is. Once the cause is resolved these @refs will come back as links on their own.

Left out of scope

  • defStela: present as WIP in the stela working tree (defStela.hpp/.cpp untracked, moving stela→ADT / valStela→concrete), but not committed yet, so it's excluded from the doc. When that refactor merges, the stela class section and diagrams will need reworking.
  • stela CHANGELOGS.md: stuck at v0.1.7 (07-20), missing visitor / writer / arrays. It's a different repo, so it's not handled here.

The architecture document still described the module as it stood before
the visitor landed, so stelaVisitor, stelaVisitInfo, stelaWriter,
strStela and arrStela went unmentioned, as did sub(index), add(), del(),
has() and len(). The class diagrams listed three subclasses out of five.

Bump the stela pin along with it: the array support being documented
here is not in 3d39295, and the @ref links would dangle without it.

The verStela example could not compile -- it bound the tstr returned by
parse() to a stela& and then used -> on it. Every C++ example in this
document is now compiled and run against stela ade6414.

Claude-Session: https://claude.ai/code/session_01SYqFWgKvvCf4untQ9sGvDQ
@codecov

codecov Bot commented Sep 4, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@kniz kniz left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

-1

+ sub(index) : stela&
+ operator[](name) : stela&
+ add(child) : void
+ del(name) : void

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

모든 걸 적는게 아니라, 중요 함수만 일부로 적은거야.

Comment thread doc/ref/ko/aj-architecture-stela.md Outdated
자식은 이름을 key로 하는 `std::map`에 담깁니다. 그래서 이름으로 찾는 `sub(name)` 외에도
n번째 자식을 꺼내는 `sub(index)`, 자식 수를 세는 `len()`, 존재를 확인하는 `has(name)`,
그리고 직접 순회할 수 있는 `begin()`과 `end()`가 제공됩니다. 트리를 고칠 때는 `add()`와
`del()`을 쓰면 되죠.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

무조건 마지막 문장 어미에 "되죠"를 붙이지마. 여기선 됩니다. 내지는 "되요"가 어울려

Comment thread doc/ref/ko/aj-architecture-stela.md Outdated

### strStela 클래스 - 문자열 값

@ref by::strStela "strStela" 는 @ref by::valStela "valStela" 를 상속하지만 메서드를 하나도

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

내용에 비해서 너무 장황해. 이렇게 굳이 섹션을 만들지 않아도 되 보이는데. 그리고 2,3줄이면 충분히 될것 같다.

Comment thread doc/ref/ko/aj-architecture-stela.md Outdated
verStela& maxVer = pkg["maxVersion"].cast<verStela>();
// 1.0.0 <= 2.1.5 <= 3.0.0 범위 확인 가능
// 버전 범위 체크. 비교 연산자가 모두 정의되어 있습니다.
verStela& minVer = pkg["minVersion"].cast<verStela>() OR_ASSERT(minVer);

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

괜히 OR_ASSERT 넣어서 복잡하게 만들지마. 이건 예제야. 핵심을 보여주기 위한거지, 완벽한 코드를 작성할필요가 없다고.

ASSERT_TRUE(ver <= maxVer);
```

### arrStela 클래스 - 배열

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

이것도 너무 장황해. 그냥 기본 타입의 interface를 그대로 사용하고 writer나 visitor가 구분을 위해서 도입된 클래스인데 뭐라도 거창한게 있는 것처럼 작성되어있어. 피곤해.

ASSERT_STREQ(collector.names[1].c_str(), "c");
```

### accept와 VISIT 매크로

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

역시 너무나 거창해. 말만 길고, 알맹이가 별로 없어.

때는 세 곳을 함께 손봐야 합니다</b>. `visitee.inl`에 `X(T)`를 등록하고, 헤더에
`BY(CLASS(T, ...), VISIT())`를 넣고, 구현에 `BY(DEF_ME(T), DEF_VISIT())`를 넣으면 되죠.

### stelaVisitInfo 클래스 - 순회 문맥

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

별로 안중요한 섹션이야. 모든 걸 설명할 셈이야?

Comment thread doc/ref/ko/aj-architecture-stela.md Outdated
byeol core의 visitInfo와 거의 같지만 `additionalLen`은 없습니다. stela에는 대응되는 개념이
없거든요.

### stelaWriter 클래스 - 트리를 소스로

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

이상한 일본 영화 같은 부제 넣지마.

Comment thread doc/ref/ko/aj-architecture-stela.md Outdated
### stelaWriter 클래스 - 트리를 소스로

@ref by::stelaWriter "stelaWriter" 는 @ref by::stelaVisitor "stelaVisitor" 를 상속해서 만든
직렬화기입니다. 트리를 순회하면서 stela 소스 텍스트를 만들어 내죠. `write()`는 결과를 문자열로

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

직렬화기라는 표현 매우 어색해.

Comment thread doc/ref/ko/aj-architecture-stela.md Outdated
ASSERT_TRUE(stelaWriter().writeFile(*root, "manifest.stela"));
```

<b>무엇이 보존되고 무엇이 사라지는가</b>

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

이것도 지나치게 복잡하게 적었어. 그냥 경고차원에서 "원본의 주석/공백등은 제거되는 방식으로 write됩니다." 표현하려는 거잖아. 길게 쓴다고 니가 유식하게 되는게 아니야.

Addressing review feedback:
- Condense verbose sections: strStela, arrStela, accept/VISIT,
  stelaVisitInfo, stelaWriter's preserved/dropped notes, visitor intro
- Drop OR_ASSERT from examples (examples should show only the essence)
- Keep only the important methods in the stela class diagram
- Clean up trailing "되죠" sentence endings
- Remove the "직렬화기" wording and the "트리를 소스로" subtitle

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FNacWrsB9saE7d1DH8zX2F
@kniz
kniz force-pushed the doc/stela-visitor-writer-arrays branch from b25f532 to 08d66fe Compare September 5, 2026 15:31
@kniz
kniz merged commit 8c3bfba into main Sep 6, 2026
10 checks passed
@kniz
kniz deleted the doc/stela-visitor-writer-arrays branch September 6, 2026 03:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant