DOCUMENTATION_GUIDELINES.md

Documentation Guidelines

This document is a work in progress and contains the current guidelines that should be followed when working on documentation.

This document is not a holy scripture and we're always open for discussion. However when an agreement is found, you should follow this document to keep the documentation consistent.

If you're not sure, contact us on our Slack Channel (see #4 or #24 for more information on that).

TL;DR

Sorry, but you will need take your time reading the document if you want to know more about the guidelines.

This document talks about the structure of the operator documentation, the method signature and the guidelines in our code examples.

Documentation Format

The documentation is created in a ts file under src/operator-docs. Normally the file for the operator should already have been created. If that's not the case, recheck all subfolders/categories to be sure (it's easy to overlook with all of those operators). If you still cannot find the operator, create the file in the category that most fits the use case.

The ts file contains an object that implements the OperatorDoc interface. All properties are optional:

• name: the name of your operator
• operatorType: any one of these strings 'combination' | 'conditional' | 'creation' | 'error handling' | 'filtering' | 'multicasting' | 'transformation' | 'utility'
• signature: the signature of the operator method (without using generics)
• useInteractiveMarbles: currently not used, but should be true for an interactive marble diagram
• marbleUrl: the url for a marble diagram (use the existing image url found on http://reactivex.io/rxjs for a static diagram)
• parameters: OperatorParameters[]. Every OperatorParameters implementation takes
  • the name of the parameter
  • the type (string, number, Observable,...)
  • the attribute (optional,...)
  • the description explaining what the parameter is used for
• shortDescription: { description: string; extras?: OperatorExtra[] }
  • [HTML] the short description of what the operator does (a TL;DR text)
  • 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.
• walkthrough: { description: string; extras?: OperatorExtra[] }
  • [HTML] the long and well explained description of what the operator does (the technically correct description and explanation)
  • 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.
• examples: one or more examples demonstrating the use of the operator
  • name: Text explaining what the example code does
  • code: The code used in your example. This code will get copied if the user clicks on the copy icon above the code example.
  • 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)
• additionalResources: OperatorReference[]
  • url towards an additional resource explaining the operator (like a blog post, youtube video,...)
  • description used as text for the link
  • author: the author of the resource (currently not used/shown)
• relatedOperators: names of other operators related to the current one

Method signature

The signature of the method should contain the correct name, parameters and return type of the method. We don't want to show any generics (like <T>) in the signature, because in most cases it does not add any value. See #196 for the discussion on this topic.

Code examples

In the example code we want to make use of ES6/TS imports as well as the pipeable operators. See #196 for a discussion on this topic. 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.

Currently to have the best of both worlds, try to follow this guideline:

• 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.
• The code in the running example on jsbin/jsfiddle should work, so in other words, use the older syntax.

The example code should also contain a comment which shows the expected output on the console. This comment should be put after/below the subscribe call on the observable.

In our examples we are currently not making use of the finnish notation ($ suffix). To be consistent with the other examples, neither should you.

Here's an example for both the inline code as well as one on jsbin:

INLINE

import { fromEvent } from 'rxjs/observable/fromEvent';
import { bufferCount } from 'rxjs/operators';

const clicks = fromEvent(document, 'click', e => ({x: e.clientX, y: e.clientY}));
const buffered = clicks.pipe(
  bufferCount(2)
);
buffered.subscribe(x => console.log(x));

/*
  Example console output:

  [[object Object] {
    x: 235,
    y: 140
  }, [object Object] {
    x: 63,
    y: 45
  }]

  [[object Object] {
    x: 199,
    y: 74
  }, [object Object] {
    x: 133,
    y: 181
  }]

  [[object Object] {
    x: 343,
    y: 174
  }, [object Object] {
    x: 274,
    y: 82
  }]
*/

JSBIN

const clicks = Rx.Observable.fromEvent(document, 'click', e => ({x: e.clientX, y: e.clientY}));
const buffered = clicks.bufferCount(2);
buffered.subscribe(x => console.log(x));
/*
  Example console output:

  [[object Object] {
    x: 235,
    y: 140
  }, [object Object] {
    x: 63,
    y: 45
  }]

  [[object Object] {
    x: 199,
    y: 74
  }, [object Object] {
    x: 133,
    y: 181
  }]

  [[object Object] {
    x: 343,
    y: 174
  }, [object Object] {
    x: 274,
    y: 82
  }]
*/