RxLua/doc/CONTRIBUTING.md

Contributing

Organization

Source is contained in the src directory. There is roughly one Lua file for each class, though the operators are stored in their own files in the src/operators directory.

Tooling

There are a number of scripts in the tools folder that automate certain tasks. In general, they are run using lua tools/<file>.lua from the project root and take no arguments.

• Everything in the src directory is concatenated into a single rx.lua file in the project root. The file tools/build.lua does this concatenation. It strips out both the requires at the top of files and the return values at the bottom.
  • If you want to create a luvit build with additional features, you can run lua tools/build.lua luvit.
• The documentation in doc/README.md is automatically generated based on comments in the source. The file tools/update_documentation.lua performs this generation. Internally it uses docroc, which is a library that parses Lua comments and returns them in a table. From here, update_documentation converts the table to markdown and writes it to the doc directory.
• Currently, you should run both of these scripts and include an updated rx.lua and doc/README.md as part of a pull request. If you've added a new file you'll have to add it (alphabetized) to the file list in tools/build.lua.

Tests

• Tests are recommended when adding new functionality. The reason is that they demonstrate correct behavior, provide a form of documentation, and protect against future bugs.
• RxLua uses lust for testing.
• To run the tests, run lua tests/runner.lua from the project root.
• To run a specific test file, run lua tests/runner.lua average to just run the tests in tests/average.lua.
• In addition to lust's default operators, there are also a few additional utilities available via runner.lua:
  • expect(Observable).to.produce(...) will assert that the Observable produces the specified values, in order. If you need to assert against multiple values emitted by a single onNext, you can pass in a table (i.e. {{1, 2, 3}, {4, 5, 6}} to check that an Observable calls onNext twice with 3 values each).
  • There is also expect(Observable).to.produce.nothing().
  • local onNext, onError, onCompleted = observableSpy(observable) will create three spies for each of the three events. You can read more about spies on lust's README.

Style

Aim for a consistent style.

• Wrap lines to 100 characters.
• Indent using two spaces.
• Document functions using docroc syntax so documentation gets automatically generated. In general this means starting your first comment with three dashes, then using @arg and @returns.
• Tend to avoid single line ifs (i.e. if condition then action end).
• Files should end in a single trailing newline with no extra blank lines. This ensures that the base rx.lua file gets concatenated correctly.