본문으로 건너뛰기
시골프로그래머의 블로그
블로그 메뉴

Delphi에서 /// XML 문서 주석을 편집하고 API 문서로 — XmlDocPlugin

Delphi IDE 안에서 C# 방식의 /// XML 주석을 WYSIWYG 편집기로 쓰고, 프로젝트 API 문서를 HTML·Markdown·CHM·JSON으로 만드는 플러그인과 명령줄 도구입니다.

풀빛컴퓨팅3분 읽기#오픈소스#Delphi#API 문서#IDE 플러그인

C#에서는 메서드 위에 ///로 XML 주석을 다는 것이 흔한 습관입니다. Delphi에는 이런 주석을 쓰고 관리하는 도구가 들어 있지 않습니다. 지금 쓸 수 있는 도구는 DevJet Software의 상용 제품 Documentation Insight 정도인데, 개인 개발자나 작은 팀, 오픈소스 기여자에게는 라이선스 비용이 부담이 됩니다.

XmlDocPlugin은 이 빈자리를 채우려고 만든 오픈소스 플러그인입니다. IDE 안에서 주석을 편집하고, 같은 엔진으로 프로젝트 전체의 API 문서를 만듭니다.

Doc Inspector 창

무엇을 하나

IDE 플러그인(BPL)에서 쓰는 기능입니다.

기능 내용
Doc Inspector 커서가 있는 코드 요소의 문서를 바로 편집하는 도킹 패널
Documentation Explorer 유닛의 클래스, 메서드, 속성을 트리로 보며 문서 편집
WYSIWYG 편집기 TipTap 기반 편집기를 TEdgeBrowser(WebView2)로 띄움
문서 틀 만들기 단축키 하나로 매개변수, 반환형, 제네릭 형식 매개변수까지 채운 틀 생성
미작성 요소 이동 문서가 없는 요소를 차례로 찾아감
커버리지 보고서 프로젝트에서 문서가 달린 비율을 분석

단축키는 모두 바꿀 수 있습니다.

문서 생성 엔진(HelpGen)은 HTML, Markdown, CHM, JSON으로 내보냅니다. 형식과 멤버 사이 상호 참조 링크를 자동으로 만들고, HTML 테마를 바꾸거나 독립된 API 문서 사이트로 내보낼 수 있습니다.

써 보기

지원하는 태그는 <summary>, <param>, <returns>, <remarks>, <value>, <typeparam>, <exception>, <example>, <seealso>입니다.

/// <summary>Retrieves information for the specified user.</summary>
/// <param name="AUserId">The ID of the user to look up</param>
/// <returns>User info, or nil if not found</returns>
/// <exception cref="EAuthException">Raised when not authenticated</exception>
function GetUser(const AUserId: Integer): TUser;

IDE 밖에서는 명령줄 도구 XmlDocGen으로 문서를 만듭니다. CI/CD 파이프라인에 넣을 때 씁니다.

XmlDocGen -d "C:\MyProject\src" -o "C:\MyProject\docs" -f HTML,MD

빌드

Delphi 11 Alexandria 이상(TEdgeBrowser 필요), Node.js 18 이상, WebView2 런타임이 필요합니다. WebView2는 Windows 10/11에 기본으로 들어 있습니다.

# 1. Build the web editor
cd web
npm install
npm run build

# 2. Compile resources
cd ../src/Plugin
brcc32 XmlDocEditor.rc

# 3. Build the BPL in Delphi
# Open src/Packages/13/XmlDocPlugin.dpk → Build + Install

어떻게 만들었나

소스 구문 분석은 DelphiAST가 맡고, IDE 연동은 Open Tools API로 합니다. 편집기는 TypeScript와 TipTap으로 만들어 Vite로 HTML 파일 하나에 묶은 뒤 리소스로 넣습니다. 파서, 모델, 코드 생성 같은 핵심 모듈은 src/Core에 두고 IDE 플러그인과 명령줄 도구가 함께 씁니다. 테스트는 DUnitX로 작성했습니다.

화면

Documentation Explorer 창

알아 둘 점

  • 라이선스는 MIT입니다. 구문 분석에 쓰는 DelphiAST는 MPL 2.0입니다.
  • 패키지 프로젝트는 src/Packages/13/에 있습니다.

소스와 스크린샷은 GitHub 저장소에 있습니다.

함께 읽으면 좋은 글