발표는 먼저 RBS 3.9 및 Steep 1.0의 최근 업데이트 사항을 소개합니다. 여기에는 제네릭 타입 파라미터 지원, 타입 오류 무시 기능, Steep 파일 DSL을 통한 프로젝트 구성 개선, type_names_matic 명령어를 통한 RBS 파일 로딩 속도 향상, 중복 타입/메서드/상수 보고 기능 등이 포함됩니다. 또한, 인라인 RBS 선언 지원은 여전히 개발 중인 주요 기능으로 언급됩니다.
Steep이 제공하는 문서화 기능은 개발자의 코드 읽기 및 작성 경험을 향상시키는 데 중점을 둡니다. 주요 기능으로는 ▲호버(Hover): 코드 요소에 마우스를 올리면 관련 문서 표시, ▲자동 완성(Completion): 메서드 이름 입력 시 관련 메서드 목록과 문서 제공, ▲시그니처 도움말(Signature Help): 메서드 인자 작성 시 가능한 파라미터 목록 및 메서드 문서 표시 등이 있습니다. 이러한 문서 정보는 RBS 파일 내에 마크다운 형식으로 작성된 주석에서 가져오며, Language Server Protocol(LSP)을 통해 편집기와 Steep 간의 실시간 통신으로 제공됩니다.
Steep의 문서화 시스템은 전통적인 RDoc이나 YARD와는 다른 접근 방식을 취합니다. RDoc과 YARD가 HTML이나 PDF와 같은 정적 문서를 생성하는 반면, Steep은 사용자의 편집기 상호작용에 따라 문서를 실시간으로 생성하고 표시합니다. 내부적으로 RBS 파일은 추상 구문 트리(AST)로 파싱되며, 각 구문 요소에 주석이 연결됩니다. Steep의 타입 검사기는 Ruby 프로그램의 각 노드에 타입을 할당하고, 이 정보를 바탕으로 해당 타입이나 메서드에 연결된 주석을 찾아 편집기로 전송합니다.
하지만 현재 구현에는 비효율적인 문제가 존재합니다. RBS 파일의 주석만 변경되어도 타입 검사기가 전체 타입 검사를 다시 실행해야 합니다. 이는 문서 시스템과 타입 검사기 간의 긴밀한 결합, 특히 오버로드 데이터 구조의 업데이트 때문입니다. 이를 해결하기 위해 발표자는 ‘문서 인덱스(Documentation Index)’ API 도입을 제안합니다. 이 인덱스는 문서 시스템을 타입 검사기로부터 분리하여, 주석 변경 시에는 인덱스만 업데이트하고 타입 검사는 불필요하게 실행되지 않도록 합니다. 또한, 인덱스를 직렬화하여 서버 재시작 후에도 재사용하거나 네트워크를 통해 배포할 수 있는 이점을 제공합니다.
인덱스 API의 핵심은 안정적인 식별자 설계입니다. 클래스 문서의 경우 클래스 이름이 식별자가 될 수 있지만, 메서드 오버로드의 경우 복잡성이 증가합니다. 파일명과 줄 번호는 편집 시 변경될 수 있어 불안정하며, 오버로드 인덱스는 파일 로딩 순서에 따라 달라질 수 있어 신뢰할 수 없습니다. 최종적으로 제안된 해결책은 ‘정규화된 메서드 타입’을 식별자로 사용하는 것입니다. 이는 메서드 이름 뒤에 매개변수 타입과 반환 타입을 명시하여 오버로드를 명확히 식별하며, 매개변수 이름 제거 및 키워드 인자 정렬을 통해 정규화됩니다. 이는 JVM의 메서드 디스크립터와 유사한 방식으로, 변경 시 타입 검사가 필요하다는 점은 있지만, 항상 최신 타입 정보에 기반하므로 합리적입니다.