이 이야기의 시작은...

바야흐로 HangulKit의 Swift DocC 튜토리얼 문서를 작성하고 있을 때로 거슬러 올라갑니다... 그리고 현재진행형...

튜토리얼 문서를 들어가보시면 아시겠지만, DocC로는 반응형 튜토리얼을 만들 수 있는데요. SwiftUI와 유사?동일?한 문법으로 작성해주면 알아서 이런 아주 기깔나는 튜토리얼을 뽑아줍니다.

다만 사소한 문제점이 있습니다.

그것은 어떤 소프트웨어라도 피할 수 없는 숙명...

바로 버그가 있다는 것이죠.

DocC는 Tutorial을 작성할 때, code1.swift와 code2.swift라는 파일을 생성해서 각각 코드를 작성하고, 그 코드를 튜토리얼 내부의 단계, @Steps안의 @Step에서 불러와서 비교를 할 수 있습니다.

그러니까, code2.swift를 바로 직전 코드인 code1.swift와 비교를 해서 다른 부분을 강조해서 표시해주는 기능이 있답니다. 옵션에 따라 바로 직전 코드가 아니라 다른 코드를 비교하게 할 수도 있구요!

뭐 대충 위의 스크린샷과 같은 느낌입니다.

근데 스크린샷을 보고 "잘 되는 거 아니냐? 무슨 버그가 있다는 거냐"고 하시면...

코드 변경점 강조가 간헐적으로 안 되더라고요. 왜인지 (당시에는) 몰랐구요.

나만 겪는 문제가 아니었다

그래서 대충 짧(지않았고찾는데꽤시간이걸렸지만그냥설명하기귀찮아서생략)은 구글링을 마치니, Swift DocC GitHub Repo에 이슈가 이미 등록되어 있더라고요!

그래서 일단 버그를 재현해보았습니다

부분적으로 코드를 지워보기도 하고,
같은 문제를 겪던 다른 2명의 개발자 분들의 코드도 뜯어보고 하며,
(여기도 자세한 설명은 생략)
결국은 재현해내는데 성공을 했답니다!

이슈에 기록이 남아있으니 직접 보시는 것도 좋지만, 또 글을 읽으러 온 분들에게 각박하게 페이지에서 쫓아내는 것도 도리가 아니기에 친절하지만 간략하게 설명을 드리자면:

@Steps {
    @Step {
        첫번째 스텝입니다.
        @Code(file: code1.swift, name: somefile.swift)
    }
    @Step {
        두번째 스텝입니다.
        @Code(file: code2.swift, name: somefile.swift)
    }
    @Step {
        세번째 스텝입니다.
        @Code(file: code2.swift, name: somefile.swift)
    }
}

요로코롬 두번째와 세번째 @Step에서 똑같은 코드 파일을 사용할 경우 뭔가 내부적으로 꼬이면서 첫번째 @Step에서 두번째 @Step으로 넘어갈 때 code1.swift와 code2.swift의 차이점이 강조가 되지 않는 것이었습니다.

근데 말이죠...

관련해서 정리하여 이슈에 코멘트를 남기고 난 얼마 뒤...

무려 애플 개발자피셜

버그 아니고 의도된 동작이라는 답변을 주셨는데요...!

답변을 요약하자면:

두 개 이상의 @Steps가 하나의 코드 파일을 지칭하고 있을 경우, DocC는 현재 @Step의 코드를 직전의 @Step과 비교하고, 현재 @Step과 직전 @Step의 (코드가) 같으니, 강조가 되지 않을 것이다.

인데요...

뭐지 그럼 내가 틀린건가?

근데 아무리 생각해봐도 이상한 겁니다.

1. 답변이 맞다고 해도, 첫번째와 두번째 단계에선 여전히 (다른 코드이니) 변경점이 표시되어야 하는 것이 아닌가?
2. 그럼 왜 세번째 단계를 빼면 버그가 사라지는가?

그래서...

아뇨 잘못된 건 잘못된 거죠!

위에서 설명한 것처럼 그게 그렇게 되면 안 되는 거 아니냐고요~라는 내용의 코멘트를 이슈에다가 또 달았는데요, 궁금하면 이슈에 있으니 참고바라요

이 글을 쓰고 있는 현 시간 기준으로 아직 별 다른 코멘트가 없으시네요... 많이 바쁘신가봅니다...

(나도바쁜데나도9to6풀타임근무뛰고남는시간쪼개서하는건데)

그래서... 일단 제 나름대로의 해결책을 생각해보자면...

해결책

1. 공식 문서에 @Code(file:name:)를 사용할 땐 중복 파일을 사용하지 말라고 명시

가장 간단하죠? 암것도 안 고쳐도 되고 그냥 버그나니까 하지마!라고 해버리면 되는 군대식 해결책!

하지만 뭐랄까... 그렇게 한다면 파일을 하나 더 생성해야하는 수고가 있잖아요...

하나의 파일을 단 한 번만 불러서 쓸 수 있다면 튜토리얼 때 같은 파일의 내용을 여러 번 사용하고 싶을 때 계속 새로 파일을 만들어야 하는데.. 파일도 많아지고 복잡하잖아요...

그래서 생각해본 다음 해결책은?

2. 같은 코드파일을 지목하고 있어도 알아서 잘 표시해준다.

근데 또 여기엔 내부 로직에서 두 가지 갈래가 있거든요?

내부적으로 같은 코드 파일 이름을 지칭하고 있으면:

1. 동일한 파일을 이름만 다르게 두 개 생성해서 이름만 다르게,
   그러니까 code2a, code2b 이런 식으로 해서
   알아서 두 개의 파일을 만들어주는 것. (이러면 기존 로직에 덧붙이게 되겠죠)
2. 알아서 잘 표시가 되게 기존 로직을 수정한다.

글로만 봐도 좀 복잡해보입니다.

그래서 DocC를 포크해서 직접 이것저것 만져보고, 괜찮은 해결책이 나오면 PR까지도 날려볼 생각으로,

DocC를 직접 건드려 보려고 했는데요...

여기서부터 또 난장판이었거든요...
그건 이제 다음 시간에... 찾아옵니다...

그럼