It'd be helpful for people familiar with Rx if methods like -flattenMap: and interfaces like RACSignal indicated the corresponding concepts in Rx that they're equivalent to.
A primer for people coming from Rx with an overview of the differences would be better. That way all that information is in one place and easily reference-able, instead of spread throughout methods and headers.
That makes sense for conceptual differences, but I don't agree for 1-to-1 correspondence. That means the information will get out-of-date faster, won't scale well (since we'll keep adding to this one list of differences), and won't cross-reference well with method documentation (i.e., you can't then look at a method and see "Oh, this is XYZ from Rx!").
True, but it's harder to find XYZ from Rx if you don't know what it is in RAC to begin with if you have to look in <RACStream>, RACSignal and <RACSignal> each time.
Still, your points are better, I agree expanding existing method docs is better than adding a different doc.
Hopefully those cases will be caught by text search (whether in headers or, eventually, generated documentation). It's nice to describe concepts in a single spot for exactly this reason – because there aren't a couple easy keywords to search for.
+1 I got a little lost in the new API. (Coming straight from 0.8) As a side question: what can I use for selectMany? THX