Skip to content
This repository was archived by the owner on Oct 1, 2018. It is now read-only.

Commit 5edd48f

Browse files
Merge pull request #248 from DiedrikDM/documentation-guidelines
chore(guidelines): Add guidelines on the documentation
2 parents 1ba4c83 + d80d4a8 commit 5edd48f

File tree

1 file changed

+160
-0
lines changed

1 file changed

+160
-0
lines changed

DOCUMENTATION_GUIDELINES.md

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
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

Comments
 (0)