Add details to docs/styleguide.md

diff --git a/docs/styleguide.md b/docs/styleguide.md
index 21d7c63..932a7b0 100644 (file)
--- a/docs/styleguide.md
+++ b/docs/styleguide.md
@@ -1,66 +1,169 @@
 # Electron Documentation Styleguide
 
-Find the appropriate section for your task: [reading Electron documentation](#reading-electron-documentation)
-or [writing Electron documentation](#writing-electron-documentation).
+These are the ways that we construct the Electron documentation.
 
-## Writing Electron Documentation
+## Titles
 
-These are the ways that we construct the Electron documentation.
+Each page has only one `#`-level title on the top, following chapters in the
+same page must have `##`-level titles, and sub-chapters need to increase the
+number of `#` in title according to its nesting depth.
+
+For the page's title, all words must be capitalized, for other chapters, only
+the first word has to be capitalized.
+
+Using `Quick Start` as example:
+
+```markdown
+# Quick Start
+
+...
+
+## Main process
+
+...
+
+## Renderer process
+
+...
+
+## Run your app
 
-- Maximum one `h1` title per page.
-- Use `bash` instead of `cmd` in code blocks (because of syntax highlighter).
-- Doc `h1` titles should match object name (i.e. `browser-window` →
-  `BrowserWindow`).
-  - Hyphen separated filenames, however, are fine.
-- No headers following headers, add at least a one-sentence description.
-- Methods headers are wrapped in `code` ticks.
-- Event headers are wrapped in single 'quotation' marks.
-- No nesting lists more than 2 levels (unfortunately because of markdown
+...
+
+### Run as a distribution
+
+...
+
+### Manually downloaded Electron binary
+
+...
+```
+
+For API references, there are exceptions to this rule.
+
+## Markdown rules
+
+* Use `bash` instead of `cmd` in code blocks (because of syntax highlighter).
+* Line length is 80-column wrapped.
+* No nesting lists more than 2 levels (unfortunately because of markdown
   renderer).
-- Add section titles: Events, Class Methods and Instance Methods.
-- Use 'will' over 'would' when describing outcomes.
-- Events and methods are `h3` headers.
-- Optional arguments written as `function (required[, optional])`.
-- Optional arguments are denoted when called out in list.
-- Line length is 80-column wrapped.
-- Platform specific methods are noted in italics following method header.
- - ```### `method(foo, bar)` _macOS_```
-- Prefer 'in the ___ process' over 'on'
-
-### Documentation Translations
 
-Translations of the Electron docs are located within the `docs-translations`
-directory.
+## Picking words
 
-To add another set (or partial set):
+* Use "will" over "would" when describing outcomes.
+* Prefer "in the ___ process" over "on".
 
-- Create a subdirectory named by language abbreviation.
-- Within that subdirectory, duplicate the `docs` directory, keeping the
-  names of directories and files same.
-- Translate the files.
-- Update the `README.md` within your language directory to link to the files
-  you have translated.
-- Add a link to your translation directory on the main Electron [README](https://github.com/electron/electron#documentation-translations).
+## API references
 
-## Reading Electron Documentation
+Following rules only apply to documentations of APIs.
 
-Here are some tips for understanding Electron documentation syntax.
+### Page title
 
-### Methods
+Each page must use the actual object name returned by `require('electron')`
+as name, like `BrowserWindow`, `autoUpdater`, `session`.
+
+Under the page tile must be a one-line description starting with `>`.
 
-An example of [method](https://developer.mozilla.org/en-US/docs/Glossary/Method)
-documentation:
+Using `session` as example:
+
+```markdown
+# session
+
+> Manage browser sessions, cookies, cache, proxy settings, etc.
 
 ```
-`methodName(required[, optional]))`
 
-* `required` String (**required**)
-* `optional` Integer
+### Module methods and events
+
+For modules that are not classes, their methods and events must be listed under
+`## Methods` and `## Events` chapters.
+
+Using `autoUpdater` as example:
+
+```markdown
+# autoUpdater
+
+## Events
+
+### Event: 'error'
+
+## Methods
+
+### `autoUpdater.setFeedURL(url[, requestHeaders])`
 ```
 
-The method name is followed by the arguments it takes. Optional arguments are
-notated by brackets surrounding the optional argument as well as the comma
-required if this optional argument follows another argument.
+### Classes
+
+For APIs that exists as classes, or for classes that are parts of modules, they
+must listed under `## Class: TheClassName` chapter. One page can have multiple
+classes.
+
+If the class has constructors, they must be listed with `###`-level titles.
+
+The methods, events and properties of a class must be listed under
+`### Instance Methods`, `### Instance Events` and `Instance Properties`
+chapters.
+
+Using `Session`, `Cookies` classes as example:
+
+```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
+
+The chapter of method must be in the following form:
+
+```markdown
+### `objectName.methodName(required[, optional]))`
+
+* `required` String
+* `optional` Integer (optional)
+
+...
+
+```
+
+The title can be `###` or `####`-levels depending on whether it is a method of
+module or class.
+
+For modules, the `objectName` is the module's name, for classes, it must be the
+name of instance of the class, and must not be same with the module's name.
+
+For example, the methods of `Session` class under `session` module must use
+`ses` as `objectName`.
+
+The optional arguments are notated by brackets surrounding the optional argument
+as well as the comma required if this optional argument follows another
+argument.
 
 Below the method is more detailed information on each of the arguments. The type
 of argument is notated by either the common types:
@@ -68,35 +171,69 @@ of argument is notated by either the common types:
 [`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)
-or a custom type like Electron's [`webContent`](api/web-content.md).
+or a custom type like Electron's [`WebContent`](api/web-content.md).
 
-If an argument is unique to certain platforms, those platforms are denoted
-using a space-delimited italicized list following the datatype. Values can be
-`macOS`, `Windows`, or `Linux`.
+If an argument or a method is unique to certain platforms, those platforms are
+denoted using a space-delimited italicized list following the datatype. Values
+can be `macOS`, `Windows`, or `Linux`.
 
-```
+``` markdown
 * `animate` Boolean (optional) _macOS_ _Windows_
 ```
 
+For argument with `Array` type, it must be classified what elements the array
+may include in the description below.
+
+For argument with `Function` type, the description should make it clear how it
+may be called and list the types of the arguments that passed to it.
+
 ### Events
 
-An example of [event](https://developer.mozilla.org/en-US/docs/Web/API/Event)
-documentation:
+The chapter of event must be in following form:
 
-```
-Event: 'wake-up'
+```markdown
+### Event: 'wake-up'
 
 Returns:
 
 * `time` String
+
+...
+
 ```
 
-The event is a string that is used after a `.on` listener method. If it returns
-a value it and its type is noted below. If you were to listen and respond to
-this event it might look something like this:
+The title can be `###` or `####`-levels depending on whether it is an event of
+module or class.
+
+The arguments of an event have the same rules with methods.
+
+### Properties
+
+The chapter of property must be in following form:
+
+```markdown
+### session.defaultSession
+
+...
 
-```javascript
-Alarm.on('wake-up', (time) => {
-  console.log(time)
-})
 ```
+
+The title can be `###` or `####`-levels depending on whether it is a property of
+module or class.
+
+## Documentation Translations
+
+Translations of the Electron docs are located within the `docs-translations`
+directory.
+
+To add another set (or partial set):
+
+* Create a subdirectory named by language abbreviation.
+* Translate the files.
+* Update the `README.md` within your language directory to link to the files
+  you have translated.
+* Add a link to your translation directory on the main Electron
+  [README](https://github.com/electron/electron#documentation-translations).
+
+Note that the files under `docs-translations` must only include the translated
+ones, the original English files should not be copied there.