|
| 1 | +# Documentation Guidelines |
| 2 | + |
| 3 | +This document is a work in progress and contains the _current_ guidelines that should be followed when working on documentation. |
| 4 | + |
| 5 | +This document is _not_ a holy scripture and we're always open for discussion. |
| 6 | +However when an agreement is found, you should follow this document to keep the documentation consistent. |
| 7 | + |
| 8 | +If you're not sure, contact us on our Slack Channel (see [#4](https://github.com/ReactiveX/rxjs-docs/issues/4) or [#24](https://github.com/ReactiveX/rxjs-docs/issues/24) for more information on that). |
| 9 | + |
| 10 | +## TL;DR |
| 11 | +>_Sorry, but you will need take your time reading the document if you want to know more about the guidelines._ |
| 12 | +
|
| 13 | +This document talks about the [structure of the operator documentation](#documentation-format), [the method signature](#method-signature) and the guidelines in our [code examples](#code-examples). |
| 14 | + |
| 15 | +## Documentation Format |
| 16 | +The documentation is created in a ts file under src/operator-docs. |
| 17 | +Normally the file for the operator should already have been created. |
| 18 | +If that's not the case, recheck all subfolders/categories to be sure (it's easy to overlook with all of those operators). |
| 19 | +If you still cannot find the operator, create the file in the category that most fits the use case. |
| 20 | + |
| 21 | +The ts file contains an object that implements the __OperatorDoc__ interface. All properties are optional: |
| 22 | + |
| 23 | +- __name__: the name of your operator |
| 24 | +- __operatorType__: any one of these strings 'combination' |
| 25 | + | 'conditional' |
| 26 | + | 'creation' |
| 27 | + | 'error handling' |
| 28 | + | 'filtering' |
| 29 | + | 'multicasting' |
| 30 | + | 'transformation' |
| 31 | + | 'utility' |
| 32 | +- __signature__: the signature of the operator method (without using generics) |
| 33 | +- __useInteractiveMarbles__: currently not used, but should be true for an interactive marble diagram |
| 34 | +- __marbleUrl__: the url for a marble diagram (use the existing image url found on http://reactivex.io/rxjs for a static diagram) |
| 35 | +- __parameters__: OperatorParameters[]. Every OperatorParameters implementation takes |
| 36 | + - the _name_ of the parameter |
| 37 | + - the _type_ (string, number, Observable,...) |
| 38 | + - the _attribute_ (optional,...) |
| 39 | + - the _description_ explaining what the parameter is used for |
| 40 | +- __shortDescription__: { |
| 41 | + description: string; |
| 42 | + extras?: OperatorExtra[] |
| 43 | + } |
| 44 | + - [HTML] the short _description_ of what the operator does (a TL;DR text) |
| 45 | + - _extras_ containing a type of 'Tip'|'Warning' and some text for it. It will show up with a little icon to make the type of extra clear. |
| 46 | +- __walkthrough__: { |
| 47 | + description: string; |
| 48 | + extras?: OperatorExtra[] |
| 49 | + } |
| 50 | + - [HTML] the long and well explained _description_ of what the operator does (the technically correct description and explanation) |
| 51 | + - _extras_ containing a type of 'Tip'|'Warning' and some text for it. It will show up with a little icon to make the type of extra clear. |
| 52 | +- __examples__: one or more examples demonstrating the use of the operator |
| 53 | + - _name_: Text explaining what the example code does |
| 54 | + - _code_: The code used in your example. This code will get copied if the user clicks on the copy icon above the code example. |
| 55 | + - _externalLink_: an object containing a type of 'JSBin'|'JSFiddle' and the url towards a working example. (Talks are underway to also support Stackblitz in the near future) |
| 56 | +- __additionalResources__: OperatorReference[] |
| 57 | + - _url_ towards an additional resource explaining the operator (like a blog post, youtube video,...) |
| 58 | + - _description_ used as text for the link |
| 59 | + - _author_: the author of the resource (currently not used/shown) |
| 60 | +- __relatedOperators__: names of other operators related to the current one |
| 61 | + |
| 62 | +## Method signature |
| 63 | +The signature of the method should contain the correct name, parameters and return type of the method. |
| 64 | +We don't want to show any generics (like <T>) in the signature, because in most cases it does not add any value. |
| 65 | +See [#196](https://github.com/ReactiveX/rxjs-docs/pull/196#discussion_r155799478) for the discussion on this topic. |
| 66 | + |
| 67 | +## Code examples |
| 68 | +In the example code we want to make use of ES6/TS imports as well as the pipeable operators. |
| 69 | +See [#196](https://github.com/ReactiveX/rxjs-docs/pull/196#discussion_r157232289) for a discussion on this topic. |
| 70 | +However, neither jsbin nor jsfiddle support this format. When the project gets support from Stackblitz, the newer syntax should be available on that platform and is of course preferred. |
| 71 | + |
| 72 | +Currently to have the best of both worlds, try to follow this guideline: |
| 73 | +- The code created directly in the ts file (which will get copied when you click on the icon) should follow the ES6/TS imports and pipeable operators. |
| 74 | +- The code in the running example on jsbin/jsfiddle should work, so in other words, use the older syntax. |
| 75 | + |
| 76 | +The example code should also contain a comment which shows the expected output on the console. |
| 77 | +This comment should be put after/below the subscribe call on the observable. |
| 78 | + |
| 79 | +In our examples we are currently not making use of the finnish notation ($ suffix). To be consistent with the other examples, neither should you. |
| 80 | + |
| 81 | +Here's an example for both the inline code as well as one on jsbin: |
| 82 | + |
| 83 | +__INLINE__ |
| 84 | +```javascript |
| 85 | +import { fromEvent } from 'rxjs/observable/fromEvent'; |
| 86 | +import { bufferCount } from 'rxjs/operators'; |
| 87 | + |
| 88 | +const clicks = fromEvent(document, 'click', e => ({x: e.clientX, y: e.clientY})); |
| 89 | +const buffered = clicks.pipe( |
| 90 | + bufferCount(2) |
| 91 | +); |
| 92 | +buffered.subscribe(x => console.log(x)); |
| 93 | + |
| 94 | +/* |
| 95 | + Example console output: |
| 96 | +
|
| 97 | + [[object Object] { |
| 98 | + x: 235, |
| 99 | + y: 140 |
| 100 | + }, [object Object] { |
| 101 | + x: 63, |
| 102 | + y: 45 |
| 103 | + }] |
| 104 | +
|
| 105 | + [[object Object] { |
| 106 | + x: 199, |
| 107 | + y: 74 |
| 108 | + }, [object Object] { |
| 109 | + x: 133, |
| 110 | + y: 181 |
| 111 | + }] |
| 112 | +
|
| 113 | + [[object Object] { |
| 114 | + x: 343, |
| 115 | + y: 174 |
| 116 | + }, [object Object] { |
| 117 | + x: 274, |
| 118 | + y: 82 |
| 119 | + }] |
| 120 | +*/ |
| 121 | + |
| 122 | +``` |
| 123 | + |
| 124 | +__JSBIN__ |
| 125 | +```javascript |
| 126 | +const clicks = Rx.Observable.fromEvent(document, 'click', e => ({x: e.clientX, y: e.clientY})); |
| 127 | +const buffered = clicks.bufferCount(2); |
| 128 | +buffered.subscribe(x => console.log(x)); |
| 129 | +/* |
| 130 | + Example console output: |
| 131 | +
|
| 132 | + [[object Object] { |
| 133 | + x: 235, |
| 134 | + y: 140 |
| 135 | + }, [object Object] { |
| 136 | + x: 63, |
| 137 | + y: 45 |
| 138 | + }] |
| 139 | +
|
| 140 | + [[object Object] { |
| 141 | + x: 199, |
| 142 | + y: 74 |
| 143 | + }, [object Object] { |
| 144 | + x: 133, |
| 145 | + y: 181 |
| 146 | + }] |
| 147 | +
|
| 148 | + [[object Object] { |
| 149 | + x: 343, |
| 150 | + y: 174 |
| 151 | + }, [object Object] { |
| 152 | + x: 274, |
| 153 | + y: 82 |
| 154 | + }] |
| 155 | +*/ |
| 156 | + |
| 157 | +``` |
| 158 | + |
| 159 | + |
| 160 | + |
0 commit comments