From: Cheng Zhao Date: Fri, 24 Jun 2016 01:45:37 +0000 (+0900) Subject: Add details to docs/styleguide.md X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=38592aaef77b0b163a8ac9889e1381540616425b;p=platform%2Fframework%2Fweb%2Fcrosswalk-tizen.git Add details to docs/styleguide.md --- diff --git a/docs/styleguide.md b/docs/styleguide.md index 21d7c63..932a7b0 100644 --- 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.