Design guidelines and framework overview

[Coneko]

I've been reading the Rx Design Guidelines, and it occurred to me that RAC doesn't have any equivalent documentation about how to use and extend it.
Normally the method and class documentation fulfills this, but there are some edge cases, #138 for example, that aren't covered.

A general framework-level design guideline rather than a class-level explanation of specific behaviors would be clearer and easier to consult in these cases.

Not necessarily a 30+ page document like the Rx one, but a couple of notes about how the various parts fit together and what they do and don't guarantee regarding thread safety, concurrency, memory management etc.

[jspahrsummers]

If an edge case isn't documented, it's probably not intended behavior; for example, #136 and #138 are both critical bugs that need to be fixed.

I agree that RAC could use some better documentation, but, unless we're talking about examples/tutorials, I'm not sure why it needs to be external to class and method documentation – maybe with the one exception of memory management (since it's sort of a global philosophy).

[dannygreg]

"Edge cases" aside, I definitely think RAC is in need of a nice overview document. A place to explain overarching concepts of the framework and where the various classes fit in. A primer before diving into the class-based documentation.

Only having class-level documentation can be fairly disorientating when discovering a new framework.

[joshaber]

Yep, I agree an overview doc would be good. Some things don't fit naturally as documentation on one class.

[jspahrsummers]

(Edited issue title to match the discussion.)