213 lines
9.7 KiB
Markdown
213 lines
9.7 KiB
Markdown
# ลักษณะเอกสาร Electron
|
|
|
|
นี้คือกฎในการเขียนเอกสารประกอบ Electron
|
|
|
|
## หัวข้อ
|
|
|
|
* ทุกๆเพจจะมี `#` อยู่ข้างบนสุดของเอกสาร
|
|
* ทุกๆบทจะต้องมี `##` ในหัวข้อ
|
|
* ทุกๆบทย่อยจะเพิ่ม `#` ลงไปในหัวข้อตามความลึกของบทย่อย
|
|
|
|
ยกตัวอย่างเช่น `การเริ่มต้น`:
|
|
|
|
```markdown
|
|
# การเริ่มต้น
|
|
|
|
...
|
|
|
|
## โปรเซสหลัก
|
|
|
|
...
|
|
|
|
## โปรเซส render
|
|
|
|
...
|
|
|
|
## การรันแอพ
|
|
|
|
...
|
|
|
|
```
|
|
|
|
สำหรับการอ้างอิงของ API จะไม่ใช้กฎนี้
|
|
|
|
## กฎของ Markdown
|
|
|
|
* ใช้ `bash` แทน `cmd` ในการเขียน code blocks (เพราะตัวไฮไลท์ syntax)
|
|
* บรรทัดควรที่จะเริ่มต้นใหม่ที่ 80 คอลัมน์
|
|
* ไม่ควรใส่ลิสต์ที่มีมากกว่าสองชั้น (เพราะตัว render ของ markdown)
|
|
* ทุก `js` แลพ `javascript` code blocks จะไฮไลท์ด้วย
|
|
[standard-markdown](http://npm.im/standard-markdown).
|
|
|
|
## การใช้คำ
|
|
|
|
* ใช้ 'จะ' แทนที่ 'ควรจะ' ตอนอธิบายผลลัทธ์
|
|
|
|
## การอ้างอิงของ API
|
|
|
|
กฎดังต่อไปนี้จะใช้สำหรับเอกสาร API เท่านั้น
|
|
|
|
### หัวข้อเพจ
|
|
|
|
ทุกๆเพจจะใช้ชื่อของ object ที่ได้รับจาก `require('electron')` เป็นหัวข้อ อาทิเช่น `BrowserWindow`, `autoUpdater` และ `session`
|
|
|
|
ข้างล่างหัวข้อจะเป็นคำอธิบายหนึ่งบรรทัดเริ่มต้นด้วย `>`
|
|
|
|
```markdown
|
|
# session
|
|
|
|
> คำอธิบาย
|
|
```
|
|
|
|
### โมดูล methods และ events
|
|
|
|
สำหรับโมดูลที่ไม่ใช่คราสนั้น methods และ events ของมันจะต้องอยู่ในลิสต์ภายใต้บท `## Methods` และ `## Events`
|
|
|
|
ยกตัวอย่างเช่น `autoUpdater`:
|
|
|
|
```markdown
|
|
# autoUpdater
|
|
|
|
## Events
|
|
|
|
### Event: 'error'
|
|
|
|
## Methods
|
|
|
|
### `autoUpdater.setFeedURL(url[, requestHeaders])`
|
|
```
|
|
|
|
### คราส (Classes)
|
|
|
|
* คราส API หรือ คราสที่เป็นส่วนของโมดูลจะต้องอยู่ในบท `## Class: TheClassName`
|
|
* หนึ่งเพจสามารถมีหลายคราสได้
|
|
* Constructors จะต้องอยู่ใน `###`
|
|
* [Static Methods](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/static) จะต้องอยู่ในบทของ `### Static Method`
|
|
* [Instance Methods](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes#Prototype_methods) จะต้องอยู่ในบทของ `### Instance Methods`
|
|
* ทุกๆ methods ที่มีค่า รีเทิร์น(return) จะต้องเริ่มต้นคำอธิบายด้วย "Returns `[TYPE]` - คำอธิบายค่ารีเทิร์น"
|
|
* ถ้า method รีเทิร์น `Object` โครงสร้างจองมันจะอธิบายได้ด้วยการใช้ ','(โคล่อน) ตามด้วยบรรทัดใหม่ จากนั้นก็ ลิสต์ของคุณสมบัติที่ไม่เรียงกัน (เหมือนกับ parametres ของฟังค์ชั่น)
|
|
* Instance ของ Events จะต้องอยู่ในบทของ `### Instance Events`
|
|
* Instance ของ Properties จะต้องอยู่ในบทของ `### Instance Properties`
|
|
* จะเริ่มต้นด้วย "A [Type ของ คุณสมบัติ]"
|
|
|
|
ยกตัวอย่างเช่น `Session` และ `Cookies` คราส:
|
|
|
|
```markdown
|
|
# session
|
|
|
|
## Methods
|
|
|
|
### session.fromPartition(partition)
|
|
|
|
## Properties
|
|
|
|
### session.defaultSession
|
|
|
|
## Class: Session
|
|
|
|
### Instance Events
|
|
|
|
#### Event: 'will-download'
|
|
|
|
### Instance Methods
|
|
|
|
#### `ses.getCacheSize(callback)`
|
|
|
|
### Instance Properties
|
|
|
|
#### `ses.cookies`
|
|
|
|
## Class: Cookies
|
|
|
|
### Instance Methods
|
|
|
|
#### `cookies.get(filter, callback)`
|
|
```
|
|
|
|
### Methods
|
|
|
|
บท methods จะอยู่ในรูปแบบดังนี้:
|
|
|
|
```markdown
|
|
### `objectName.methodName(required[, optional]))`
|
|
|
|
* `required` String - A parameter description.
|
|
* `optional` Integer (optional) - Another parameter description.
|
|
|
|
...
|
|
```
|
|
|
|
หัวข้อจะสามารถอยู่ในรูปของ `###` หรือ `####` (ตามว่าเป็น method ของโมดูลหรือของคราส)
|
|
|
|
สำหรับโมดูล `objectName` คือชื่อของโมดูล แต่ว่าสำหรับคราสนั้น ชื่อจะต้องเป็น instance ของคราสและจะต้องไม่ซ้ำกับชื่อโมดูล
|
|
|
|
ยกตัวอย่างเช่น method ของคราส `Session` ที่อยู่ใน `session` โมดูลจะต้องใช้ `ses` เหมือนกับ `objectName`.
|
|
|
|
หากมี arguments เพิ่มเตินนั้นจะได้รับการบันทึกภายใน `[]` รวมถึงคอมม่ถ้าหากว่า arguement นี้ตามด้วย argument เสริมอื่นๆ
|
|
|
|
```
|
|
required[, optional]
|
|
```
|
|
|
|
ข้างล่าง method จะเป็นข้อคาวมโดยละเอียดเกี่ยวกับ arguments อื่นๆ, ชนิค (Type) ของ argument จะโดนบันทีกตาม type ทั่วไป
|
|
|
|
* [`String`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)
|
|
* [`Number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)
|
|
* [`Object`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
|
|
* [`Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)
|
|
* [`Boolean`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)
|
|
* หรือ type พิเศษเช่น Electron [`WebContent`](api/web-contents.md)
|
|
|
|
หาก argument หรือ method มีเฉพาะเจาะจงกับ platform นั้น ให้ใช้ตัว italic (เอียง) ลิสต์ตาม datatype
|
|
โดยที่ตัวลิสต์นั้นจะจำกัดอยู่ที่ `macOS`, `Windows`, หรือ `Linux` เท่านั้น
|
|
|
|
```markdown
|
|
* `animate` Boolean (optional) _macOS_ _Windows_ - เล่นแอนนิเมชัั่น.
|
|
```
|
|
|
|
Arguments ชนิด `Array` จะต้องบอกว่า array นั้นจะใส่อะไรลงไปตามข้อมูลด้านล่าง
|
|
|
|
ข้อความอธิบาย arguments ของ ฟังค์ชั่น (function) จะต้องบอกเจาะจงถึงวิธีการใช้งานและชนิดของ parametres ที่ฟังค์ชั่นนั้นรับ
|
|
|
|
### อีเว้น (Events)
|
|
|
|
บทอีเว้นจะต้องอยู่ในรูปแบบดังนี้:
|
|
|
|
```markdown
|
|
### Event: 'wake-up'
|
|
|
|
Returns:
|
|
|
|
* `time` String
|
|
|
|
...
|
|
```
|
|
|
|
หัวข้อจะสามารถอยู่ในรูปของ `###` หรือ `####` (ตามว่าเป็นอีเว้นของโมดูลหรือของคราส)
|
|
|
|
แบบเอกสาร arguments ของอีเว้นจะใช้กฎเดียวกับ methods
|
|
|
|
### คุณสมบัติ (Properties)
|
|
|
|
บทคุณสมบัติจะต้องอยู่ในรูปแบบดังนี้:
|
|
|
|
```markdown
|
|
### session.defaultSession
|
|
|
|
...
|
|
```
|
|
|
|
หัวข้อจะสามารถอยู่ในรูปของ `###` หรือ `####` (ตามว่าเป็นคุณสมบัติของโมดูลหรือของคราส)
|
|
|
|
## การแปลเอกสาร
|
|
|
|
เอกสารของ Electron ที่ถูกแปลแล้ว จะอยู่ในโฟลเดอร์ `docs-translation`
|
|
|
|
ในการสร้างเซ็ตของภาษาใหม่ (เพิ่มในบางส่วน)
|
|
|
|
* สร้างที่อยู่ย่อยตามตัวย่อของภาษา
|
|
* แปลภาษา
|
|
* อัพเดท `README.md` ภายในเพื่อเป็นสารลิงค์ไฟล์ต่างๆที่แปลแล้ว
|
|
* เพิ่มลิ้งค์ลง [README](https://github.com/electron/electron#documentation-translations) หลักของ Electron
|
|
|
|
โน้ต: ไฟล์ที่อยู่ใน `docs-translations` จะมีแค่ที่แปลแล้วเท่านั้น ไฟล์ต้นตำรับภาษาอังกริษไม่ควรจะโดนก้อปปี้ลงไปด้วย
|