From 5dd7bf67e7792cfecd428102d3965885774e5b3f Mon Sep 17 00:00:00 2001 From: Kevin Sawicki Date: Fri, 24 Jun 2016 12:28:41 -0700 Subject: [PATCH] Minor formatting and wording tweaks --- docs/styleguide.md | 67 +++++++++++++++++++++++++++--------------------------- 1 file changed, 34 insertions(+), 33 deletions(-) diff --git a/docs/styleguide.md b/docs/styleguide.md index 932a7b0..34d20df 100644 --- a/docs/styleguide.md +++ b/docs/styleguide.md @@ -1,12 +1,12 @@ # Electron Documentation Styleguide -These are the ways that we construct the Electron documentation. +These are the guidelines for writing Electron documentation. ## Titles 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. +number of `#` in the 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. @@ -43,10 +43,9 @@ 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). +* Use `bash` instead of `cmd` in code blocks (due to the syntax highlighter). +* Lines should be wrapped at 80 columns. +* No nesting lists more than 2 levels (due to the markdown renderer). ## Picking words @@ -55,12 +54,12 @@ For API references, there are exceptions to this rule. ## API references -Following rules only apply to documentations of APIs. +The following rules only apply to the documentation of APIs. ### Page title Each page must use the actual object name returned by `require('electron')` -as name, like `BrowserWindow`, `autoUpdater`, `session`. +as the title, such as `BrowserWindow`, `autoUpdater`, `session`, etc. Under the page tile must be a one-line description starting with `>`. @@ -78,7 +77,7 @@ Using `session` as example: For modules that are not classes, their methods and events must be listed under `## Methods` and `## Events` chapters. -Using `autoUpdater` as example: +Using `autoUpdater` as an example: ```markdown # autoUpdater @@ -94,17 +93,17 @@ Using `autoUpdater` as example: ### 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 +For APIs that exists as classes, or for classes that are part of modules, they +must listed under a `## 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` +`### Instance Methods`, `### Instance Events`, and `Instance Properties` chapters. -Using `Session`, `Cookies` classes as example: +Using `Session`, `Cookies` classes as an example: ```markdown # session @@ -140,7 +139,7 @@ Using `Session`, `Cookies` classes as example: ### Methods -The chapter of method must be in the following form: +The methods chapter must be in the following form: ```markdown ### `objectName.methodName(required[, optional]))` @@ -153,13 +152,14 @@ The chapter of method must be in the following form: ``` The title can be `###` or `####`-levels depending on whether it is a method of -module or class. +a module or a 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. +name of the instance of the class, and must not be the same as the module's +name. -For example, the methods of `Session` class under `session` module must use -`ses` as `objectName`. +For example, the methods of the `Session` class under the `session` module must +use `ses` as the `objectName`. The optional arguments are notated by brackets surrounding the optional argument as well as the comma required if this optional argument follows another @@ -167,29 +167,30 @@ argument. Below the method is more detailed information on each of the arguments. The type of argument is notated by either the common types: -[`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) -or a custom type like Electron's [`WebContent`](api/web-content.md). + +- [`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) +- Or a custom type like Electron's [`WebContent`](api/web-content.md) 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 +```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 any 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. +For any argument with `Function` type, the description should make it clear how +it may be called and list the types of the arguments that will be passed to it. ### Events -The chapter of event must be in following form: +The events chapter must be in following form: ```markdown ### Event: 'wake-up' @@ -203,13 +204,13 @@ Returns: ``` The title can be `###` or `####`-levels depending on whether it is an event of -module or class. +a module or a class. -The arguments of an event have the same rules with methods. +The arguments of an event have the same rules as methods. ### Properties -The chapter of property must be in following form: +The properties chapter must be in following form: ```markdown ### session.defaultSession @@ -219,7 +220,7 @@ The chapter of property must be in following form: ``` The title can be `###` or `####`-levels depending on whether it is a property of -module or class. +a module or a class. ## Documentation Translations -- 2.7.4