Repository navigation
doc(stela): document arrays, the visitor and the writer - #64
Conversation
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 Report✅ All modified and coverable lines are covered by tests. 🚀 New features to boost your workflow:
|
| + sub(index) : stela& | ||
| + operator[](name) : stela& | ||
| + add(child) : void | ||
| + del(name) : void |
There was a problem hiding this comment.
모든 걸 적는게 아니라, 중요 함수만 일부로 적은거야.
| 자식은 이름을 key로 하는 `std::map`에 담깁니다. 그래서 이름으로 찾는 `sub(name)` 외에도 | ||
| n번째 자식을 꺼내는 `sub(index)`, 자식 수를 세는 `len()`, 존재를 확인하는 `has(name)`, | ||
| 그리고 직접 순회할 수 있는 `begin()`과 `end()`가 제공됩니다. 트리를 고칠 때는 `add()`와 | ||
| `del()`을 쓰면 되죠. |
There was a problem hiding this comment.
무조건 마지막 문장 어미에 "되죠"를 붙이지마. 여기선 됩니다. 내지는 "되요"가 어울려
|
|
||
| ### strStela 클래스 - 문자열 값 | ||
|
|
||
| @ref by::strStela "strStela" 는 @ref by::valStela "valStela" 를 상속하지만 메서드를 하나도 |
There was a problem hiding this comment.
내용에 비해서 너무 장황해. 이렇게 굳이 섹션을 만들지 않아도 되 보이는데. 그리고 2,3줄이면 충분히 될것 같다.
| verStela& maxVer = pkg["maxVersion"].cast<verStela>(); | ||
| // 1.0.0 <= 2.1.5 <= 3.0.0 범위 확인 가능 | ||
| // 버전 범위 체크. 비교 연산자가 모두 정의되어 있습니다. | ||
| verStela& minVer = pkg["minVersion"].cast<verStela>() OR_ASSERT(minVer); |
There was a problem hiding this comment.
괜히 OR_ASSERT 넣어서 복잡하게 만들지마. 이건 예제야. 핵심을 보여주기 위한거지, 완벽한 코드를 작성할필요가 없다고.
| ASSERT_TRUE(ver <= maxVer); | ||
| ``` | ||
|
|
||
| ### arrStela 클래스 - 배열 |
There was a problem hiding this comment.
이것도 너무 장황해. 그냥 기본 타입의 interface를 그대로 사용하고 writer나 visitor가 구분을 위해서 도입된 클래스인데 뭐라도 거창한게 있는 것처럼 작성되어있어. 피곤해.
| ASSERT_STREQ(collector.names[1].c_str(), "c"); | ||
| ``` | ||
|
|
||
| ### accept와 VISIT 매크로 |
There was a problem hiding this comment.
역시 너무나 거창해. 말만 길고, 알맹이가 별로 없어.
| 때는 세 곳을 함께 손봐야 합니다</b>. `visitee.inl`에 `X(T)`를 등록하고, 헤더에 | ||
| `BY(CLASS(T, ...), VISIT())`를 넣고, 구현에 `BY(DEF_ME(T), DEF_VISIT())`를 넣으면 되죠. | ||
|
|
||
| ### stelaVisitInfo 클래스 - 순회 문맥 |
| byeol core의 visitInfo와 거의 같지만 `additionalLen`은 없습니다. stela에는 대응되는 개념이 | ||
| 없거든요. | ||
|
|
||
| ### stelaWriter 클래스 - 트리를 소스로 |
| ### stelaWriter 클래스 - 트리를 소스로 | ||
|
|
||
| @ref by::stelaWriter "stelaWriter" 는 @ref by::stelaVisitor "stelaVisitor" 를 상속해서 만든 | ||
| 직렬화기입니다. 트리를 순회하면서 stela 소스 텍스트를 만들어 내죠. `write()`는 결과를 문자열로 |
| ASSERT_TRUE(stelaWriter().writeFile(*root, "manifest.stela")); | ||
| ``` | ||
|
|
||
| <b>무엇이 보존되고 무엇이 사라지는가</b> |
There was a problem hiding this comment.
이것도 지나치게 복잡하게 적었어. 그냥 경고차원에서 "원본의 주석/공백등은 제거되는 방식으로 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
b25f532 to
08d66fe
Compare
aj-architecture-stela.mdwas 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: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 theIDX_WIDTHlimit### 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 클래스sub(index),add(),del(),has(),len(),begin()/end()### stela 클래스That
add()overwrites a child of the same name (f6c07ba) and thatsub(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, thearrStelathis doc describes isn't actually vendored, so the@refs break again.verStela example fix: the existing example was tagged
verifiedbut did not compile.The
stelaexample 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 actualwrite()result byte-for-byte (down to children being re-sorted alphabetically and the later-addedauthorcoming first).Rendering was also checked by running
DoxyReference-kowith #63's INPUT fix applied. All newly added sections appear, and references likeby::arrStela,by::strStela,by::stelaWriter,by::stelaVisitInfolink correctly to their class pages.Known issues
The 3
@ref by::stelaVisitorlinks don't resolve and render as plain text.stelaVisitoruses an X-macro pattern that#includesvisitee.inlinside the class body, which Doxygen can't pick up as a class. byeol core'svisitorhas 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/.cppuntracked, movingstela→ADT /valStela→concrete), but not committed yet, so it's excluded from the doc. When that refactor merges, thestelaclass section and diagrams will need reworking.CHANGELOGS.md: stuck at v0.1.7 (07-20), missing visitor / writer / arrays. It's a different repo, so it's not handled here.