Electron 문서 작성 가이드라인
이 문서는 Electron 문서를 작성할 때 따라야 할 지침을 설명한다.
헤딩 규칙
- 각 페이지는 맨 위에 단일
#레벨 제목을 가져야 한다. - 같은 페이지 내의 챕터는
##레벨 헤딩을 사용한다. - 하위 챕터는 중첩 깊이에 따라 헤딩의
#수를 증가시켜야 한다. - 페이지 제목은 APA 제목 대문자 규칙을 따라야 한다.
- 모든 챕터는 APA 문장 대문자 규칙을 따라야 한다.
Quick Start를 예시로 들면:
# Quick Start
...
## Main process
...
## Renderer process
...
## Run your app
...
### Run as a distribution
...
### Manually downloaded Electron binary
...
API 참조 문서의 경우 이 규칙에 예외가 적용될 수 있다.
마크다운 작성 규칙
이 저장소는 markdownlint 패키지를 사용해 일관된 마크다운 스타일을 유지한다. 정확한 규칙은 루트 폴더의 .markdownlint.json 파일에서 확인할 수 있다.
린터 규칙으로 커버되지 않는 몇 가지 스타일 가이드라인은 다음과 같다:
- 코드 블록에서는
cmd대신sh를 사용한다(구문 강조를 위해). - 가독성을 위해 가능하면 한 줄을 80~100자 이내로 유지한다.
- 마크다운 렌더러의 특성상 리스트를 2단계 이상 중첩하지 않는다.
- 모든
js와javascript코드 블록은 standard-markdown으로 린트한다. - 순서 없는 리스트에서는 대시(-) 대신 별표(*)를 사용한다.
단어 선택하기
- 결과를 설명할 때 "would"보다 "will"을 사용한다.
- "on" 대신 "in the ___ process"를 선호한다.
API 참조
다음 규칙은 API 문서화에만 적용된다.
제목과 설명
각 모듈의 API 문서는 require('electron')이 반환하는 실제 객체 이름을 제목으로 사용한다(예: BrowserWindow, autoUpdater, session).
페이지 제목 바로 아래에 모듈에 대한 한 줄 설명을 마크다운 인용문(>로 시작)으로 추가한다.
session 모듈을 예로 들면:
# session
> 브라우저 세션, 쿠키, 캐시, 프록시 설정 등을 관리한다.
모듈 메서드와 이벤트
클래스가 아닌 모듈의 경우, 해당 모듈의 메서드와 이벤트는 반드시 ## Methods와 ## Events 섹션 아래에 나열해야 한다.
autoUpdater를 예로 들면:
# autoUpdater
## Events
### Event: 'error'
## Methods
### `autoUpdater.setFeedURL(url[, requestHeaders])`
클래스
- 모듈의 일부이거나 API 클래스는
## Class: 클래스명챕터 아래에 나열한다. - 한 페이지에 여러 클래스를 포함할 수 있다.
- 생성자는
###수준의 제목으로 나열한다. - 정적 메서드는
### Static Methods챕터 아래에 나열한다. - 인스턴스 메서드는
### Instance Methods챕터 아래에 나열한다. - 반환 값이 있는 모든 메서드는 설명을 "
[타입]을 반환 - [반환 설명]"으로 시작한다.- 메서드가
객체를 반환하는 경우, 콜론 뒤에 줄바꿈을 하고 함수 매개변수와 같은 스타일로 속성을 나열해 구조를 지정할 수 있다.
- 메서드가
- 인스턴스 이벤트는
### Instance Events챕터 아래에 나열한다. - 인스턴스 속성은
### Instance Properties챕터 아래에 나열한다.- 인스턴스 속성은 "[속성 타입] ..."으로 시작한다.
Session과 Cookies 클래스를 예로 들면:
# session
## Methods
### session.fromPartition(partition)
## Static Properties
### session.defaultSession
## Class: Session
### Instance Events
#### Event: 'will-download'
### Instance Methods
#### `ses.getCacheSize()`
### Instance Properties
#### `ses.cookies`
## Class: Cookies
### Instance Methods
#### `cookies.get(filter, callback)`
메서드와 인자
메서드 장은 다음과 같은 형식으로 작성한다:
### `objectName.methodName(필수[, 선택]))`
* `필수` string - 매개변수 설명.
* `선택` Integer (선택) - 다른 매개변수 설명.
...
헤딩 레벨
헤딩은 ### 또는 #### 레벨로 작성할 수 있다. 이는 해당 메서드가 모듈에 속하는지 클래스에 속하는지에 따라 달라진다.
함수 시그니처
모듈의 경우 objectName은 모듈 이름을 사용한다. 클래스의 경우에는 반드시 클래스 인스턴스의 이름을 사용해야 하며, 모듈 이름과 동일하면 안 된다.
예를 들어, session 모듈 아래의 Session 클래스 메서드는 ses를 objectName으로 사용해야 한다.
옵션 인자는 대괄호 []로 표시하며, 옵션 인자 뒤에 쉼표가 필요한 경우 함께 표기한다:
필수인자[, 옵션인자]
인자 설명
각 인자에 대한 자세한 정보는 메서드 아래에 순서 없는 목록으로 정리한다. 인자의 타입은 자바스크립트 기본 타입(예: string, Promise, Object), Electron의 Cookie와 같은 커스텀 API 구조, 또는 와일드카드 any로 표기한다.
인자가 Array 타입인 경우, 배열 내부 값의 타입을 [] 약어로 표기한다(예: any[] 또는 string[]).
인자가 Promise 타입인 경우, Promise가 resolve하는 타입을 매개변수화하여 표기한다(예: Promise<void> 또는 Promise<string>).
인자가 여러 타입을 가질 수 있는 경우, 각 타입을 |로 구분한다.
Function 타입 인자의 설명에서는 함수가 어떻게 호출되는지 명확히 하고, 전달될 매개변수의 타입을 나열한다.
플랫폼별 기능
특정 플랫폼에만 해당하는 인자나 메서드는 데이터 타입 뒤에 공백으로 구분된 기울임꼴 목록으로 표시한다. 가능한 값은 macOS, Windows, Linux이다.
* `animate` boolean (optional) _macOS_ _Windows_ - 해당 기능을 애니메이션으로 표시한다.
이벤트
이벤트 장은 다음과 같은 형식을 따라야 한다:
### 이벤트: 'wake-up'
반환값:
* `time` string
...
이벤트가 모듈에 속하는지 클래스에 속하는지에 따라 제목은 ### 또는 #### 레벨로 작성한다.
이벤트의 인자는 메서드와 동일한 규칙을 따른다.
session.defaultSession
이 섹션은 다음과 같은 형식으로 작성한다:
### session.defaultSession
...
프로퍼티가 모듈에 속하는지 클래스에 속하는지에 따라 헤딩 레벨을 ### 또는 ####로 지정한다.
API 히스토리
"API 히스토리" 블록은 HTML 주석으로 감싸진 YAML 코드 블록이다. 이 블록은 클래스나 메서드의 마크다운 헤더 바로 뒤에 위치해야 한다. 예를 들면 다음과 같다:
#### `win.setTrafficLightPosition(position)` _macOS_
<!--
```YAML history
added:
- pr-url: https://github.com/electron/electron/pull/22533
changes:
- pr-url: https://github.com/electron/electron/pull/26789
description: "Made `trafficLightPosition` option work for `customButtonOnHover` window."
deprecated:
- pr-url: https://github.com/electron/electron/pull/37094
breaking-changes-header: deprecated-browserwindowsettrafficlightpositionposition
```
-->
* `position` [Point](structures/point.md)
트래픽 라이트 버튼의 커스텀 위치를 설정한다. `titleBarStyle`이 `hidden`으로 설정된 경우에만 사용할 수 있다.
이 블록은 API 히스토리 JSON 스키마(api-history.schema.json)를 따라야 한다. 이 스키마는 docs 폴더에서 찾을 수 있다. API 히스토리 스키마 RFC에는 스키마의 각 부분에 대한 예제와 상세 설명이 포함되어 있다.
API 히스토리 블록의 목적은 API가 언제/어디서/어떻게/왜 추가되었는지, 변경되었는지(주로 호환성이 깨지는 변경), 그리고 더 이상 사용되지 않게 되었는지를 설명하는 것이다.
블록에 나열된 각 API 변경 사항은 해당 변경이 이루어진 PR 링크와 함께 짧은 설명을 포함해야 한다. 해당 변경 사항이 호환성이 깨지는 변경 문서에 있다면, 헤딩 ID도 함께 포함해야 한다.
API 히스토리 린팅 스크립트(lint:api-history)는 Electron 문서의 API 히스토리 블록을 스키마에 맞게 검증하고 추가적인 검사를 수행한다. 더 자세한 내용은 테스트를 참고하면 된다.
린팅 스크립트에서 다루지 않는 몇 가지 스타일 가이드라인이 있다:
API HEADER | #### `win.flashFrame(flag)`
BLANK LINE |
HTML COMMENT OPENING TAG | <!--
API HISTORY OPENING TAG | ```YAML history
API HISTORY | added:
| - pr-url: https://github.com/electron/electron/pull/22533
API HISTORY CLOSING TAG | ```
HTML COMMENT CLOSING TAG | -->
BLANK LINE |
YAML
- 들여쓰기 시 두 칸의 공백을 사용한다.
- 주석을 사용하지 않는다.
설명
- 항상 설명을 큰따옴표로 감싸세요 (예: "예시").
- 앱 개발자에게 관련 있는 방식으로 변경 사항을 설명하고, 대문자로 시작하고, 구두점을 붙이며, 과거 시제를 사용하세요.
- 예시는 Clerk를 참고하세요.
- 설명을 간결하게 유지하세요.
- 이상적으로는 설명이 해당 헤더와 일치하도록 하세요.
- 가능한 경우 관련 PR의 릴리스 노트를 참고하세요.
- 개발자는 항상 주요 변경 사항 문서나 연결된 풀 리퀘스트를 참고해 더 자세한 내용을 확인할 수 있습니다.
위치 설정
일반적으로 API 변경 내역 블록은 클래스나 메서드가 변경된 부분 바로 뒤에 배치한다. 하지만 몇 가지 애매한 상황이 있다:
Chromium 버전 업데이트
때로는 주요 변경 사항이 기존 API와 관련이 없을 수 있다. 이런 경우 API History에 추가하지 않아도 괜찮다.
여러 API에 영향을 미치는 변경 사항
때로는 주요 변경 사항이 여러 API에 걸쳐 영향을 미치기도 한다. 이 경우, 관련된 각 API의 최상위 마크다운 헤더 아래에 API History 블록을 추가한다.
# contextBridge
<!--
```YAML history
changes:
- pr-url: https://github.com/electron/electron/pull/40330
description: "`ipcRenderer`는 더 이상 `contextBridge`를 통해 전송할 수 없음"
breaking-changes-header: behavior-changed-ipcrenderer-can-no-longer-be-sent-over-the-contextbridge
```
-->
> 격리된 컨텍스트 간에 안전한 양방향 동기식 브리지를 생성
# ipcRenderer
<!--
```YAML history
changes:
- pr-url: https://github.com/electron/electron/pull/40330
description: "`ipcRenderer`는 더 이상 `contextBridge`를 통해 전송할 수 없음"
breaking-changes-header: behavior-changed-ipcrenderer-can-no-longer-be-sent-over-the-contextbridge
```
-->
프로세스: [렌더러](../glossary.md#renderer-process)
다음과 같은 경우에는 API History 블록을 추가하지 않았다:
contextBridge.exposeInMainWorld(apiKey, api)
해당 함수 자체는 변경되지 않았고, 단지 사용 방법에만 변화가 있었기 때문이다:
contextBridge.exposeInMainWorld('app', {
- ipcRenderer,
+ onEvent: (cb) => ipcRenderer.on('foo', (e, ...args) => cb(args))
})
문서 번역
electron/i18n을 참고하세요.