docs(operator-docs): Added Merge operator documentation

[sumitarora]

Closes: #66

[codecov-io]

Codecov Report

Merging #140 into master will not change coverage.
The diff coverage is 100%.

@@           Coverage Diff           @@
##           master     #140   +/-   ##
=======================================
  Coverage   88.46%   88.46%           
=======================================
  Files           7        7           
  Lines          78       78           
  Branches        7        7           
=======================================
  Hits           69       69           
  Misses          6        6           
  Partials        3        3

Impacted Files	Coverage Δ
src/app/toolbar/toolbar.component.ts	85.71% <100%> (ø)	⬆️
src/app/shared.module.ts	100% <100%> (ø)	⬆️
src/app/toolbar/toolbar.module.ts	100% <100%> (ø)	⬆️
src/app/app.component.ts	100% <100%> (ø)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update aa9f74f...77a91dc. Read the comment docs.

[ladyleet]

@sumitarora you're awesome for doing this! @kwonoj @benlesh @jayphelps love to get your thoughts.

[benlesh]

How are we going to link this to the actual code files? @btroncone @ladyleet @kwonoj

It seems like we're going to have documentation in two places? Docs in the code in JSDoc-style comments, and Docs hard-coded in these files here.

Is @jayphelps still working on a script to pull the docs out of the code files?

Just checking.

[btroncone]

@benlesh This is biggest active question for me and why I have been a bit hesitant to start porting over operator info. If the ultimate plan is to use a script to pull from the code files and feed into this project the work going into moving this over manually will be overwritten once that's complete. I think we were stagnating on that front so we decided to start moving forward in this location.

Ultimately I guess we need to make a decision what the final source of truth will be as I think this could also have a significant impact on translations. From what I've gathered the current plan is being built around the files in this project.

[ladyleet]

I don't think we should stagnate on this project or the docs and deal with porting things over and the source of truth when we get there. I know @jayphelps has been working in this but has been sick!

[sumitarora]

@btroncone @ladyleet This is how I envisioned it to work:-

1. Operator docs should be in JSON not in TS files which should be easy to do.
2. Translations will use those JSON files to convert it in different languages eg. merge.json (for English), merge_fr.json (for French) etc.
3. The script will generate one file merge.json from docs and then run the script to generate translations from them.

We have two advantages for this we don't have to do any additional work for translations when the script is ready and we can append to existing JSON docs and even validate the script with these.

And we should keep moving forward with the current documentation so as to validate frontend end too and be ready when the script is ready.

[omfgnuts]

@sumitarora I totally agree with you, this also aligns with using ngx-translate :)

I've already started translating some stuff into Russian in offline, so I can easily copypaste my translations into merge_ru.json later on, for example.

But the initial docs need some rewriting too, I've seen long enough sentences that are hard to understand.

[hermanbanken]

@sumitarora JSON files are not multiline right? I agree that docs in TS is a bit clumsy, but it does ensures parity between code & docs as much as possible (plus, it's how everyone is doing it, looking at JavaDoc here).

I really like @jayphelps's effort to extract docs from AST on our own way instead of relying on ESDoc. The output of that process could be the input to this docs project, which could just be the HTML-shell only (+ articles/quickstarts/etc).

If we can define how this intermediary/generated docs format should look, we can move forward with rxjs-docs, right now. Think something like a TypeScript type definition for the object structure of that format.

[hermanbanken]

How about storing that intermediary/generated docs format as a JSON file in the Github releases?
That way the reactivex.io/rxjs site can be a PWA that we only have to publish once (meaning less effort for Microsoft). Every visitor downloads (automatically via JS of course) the docs file from GH releases (for the version he selects, latest by default) and stores it in LocalStorage/StorageAPI.

That way maintainers like @benlesh, @jayphelps and contributors can publish docs simultaneously with the source releases & it will always be up to date 🎉 .

[ladyleet]

@sumitarora same

[sumitarora]

@ladyleet done

[ladyleet]

thx @sumitarora ! merged!