Skip to main content

개요

BakeryVideKit 컴포넌트 문서는 document-based-comment에 정의된 Moonwave 주석 규칙을 기반으로 하며, UI 구조 지침은 bakery-vide-kit을 반드시 함께 따라야 합니다. 이 문서는 그 가운데서도 Vide 컴포넌트의 API 문서화 흐름과 @tag vide 선언 방법을 구체화합니다.

문서화 원칙​

  • 모든 컴포넌트 파일은 최상단에 --[=[ ... ]=] 블록으로 클래스 주석을 작성하고, @class, @tag vide 를 선언합니다. Moonwave 는 @class 블록 내 @within 태그를 허용하지 않으므로, 상단 주석에는 @within 을 넣지 않습니다.
  • Props, 반환 타입, 헬퍼 훅 등 외부에 노출되는 구조체는 @interface, @type, @function 을 사용하며, 각 주석에는 @within <ComponentName>을 명시해 소속을 분명히 합니다.
  • @prop를 활용해 ComponentName.Root, ComponentName.Props 등 소비자가 접근 가능한 필드를 설명하고, 내부 전용 필드의 문서는 작성하지 않습니다.
  • 작성한 내용이 BakeryVideKit 구조나 UI 톤을 변경한다면 ui-style과 bakery-vide-kit의 조건도 다시 확인합니다.

상단 클래스 주석​

클래스를 설명하는 최상단 주석에는 컴포넌트 이름과 @tag vide 를 명시합니다. 최상단 블록에는 @within 을 넣지 말고, Props/헬퍼 등 하위 주석에서 @within <ComponentName> 을 사용해 소속을 표기합니다. 설명은 한 문단으로 끝내고, 추가 규칙은 아래 섹션에서 다루십시오.

--[=[
    @class IconButton
    @tag vide

    아이콘과 텍스트를 함께 렌더링하는 기본 버튼 컴포넌트입니다.
]=]

Props와 타입 정의​

외부에서 전달받는 Props, 내부에서 반환하는 객체 타입은 모두 @interface나 @type 주석으로 문서화합니다. Props의 각 키는 .Key Type -- 설명 형태로 정의합니다.

--[=[
    @interface IconButtonProps
    @within IconButton

    IconButton 이 요구하는 속성입니다.

    .OnClick (() -> ())? -- 클릭 시 호출되는 콜백
    .Icon string -- 표시할 아이콘 이름
    .isDisabled boolean? -- 입력을 막을 때 true
]=]
export type IconButtonProps = Components.Frame.FrameProps & {
    OnClick: (() -> ())?,
    Icon: string,
    isDisabled: boolean?,
}

--[=[
    @prop IconButton.Root Instance
    IconButton 이 반환하는 루트 vide 엘리먼트입니다.
]=]

함수와 헬퍼 문서화​

공개 훅, 정적 함수, 유틸리티는 @function 또는 @within 을 사용해 컴포넌트와의 관계를 명확히 합니다. @param, @return 설명은 document-based-comment의 순서를 그대로 따릅니다.

--[=[
    @function IconButton.useHoveredState
    @within IconButton

    Hover 상태를 제어하는 훅입니다.

    @param initial boolean? -- 초기 hover 상태
    @return boolean -- 현재 hover 여부
    @return (boolean) -> () -- 상태를 강제로 지정하는 setter
]=]
function IconButton.useHoveredState(initial: boolean?): (boolean, (boolean) -> ())
    -- 구현부
end

예시 흐름​

  1. 파일 최상단에서 클래스 주석을 작성하고 @tag vide 를 선언합니다.
  2. export type ComponentProps 및 필요한 타입을 @interface로 문서화한 뒤, Props 설명을 .Key 레이아웃으로 작성합니다.
  3. 외부에 노출되는 정적 필드나 헬퍼 함수에는 @prop, @function 주석을 추가하여 소비자가 어떤 API를 사용할 수 있는지 명확히 합니다.
  4. 모든 주석은 document-based-comment의 순서를 그대로 따르며, 추가 규칙이 필요할 경우 해당 문서의 어드머니션 예제를 활용합니다.

위 순서를 지키면 BakeryVideKit 컴포넌트는 자동으로 Vide 태그 기반 API 문서에 반영됩니다.