{"action":"created","comment":{"url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/pulls/comments/30928987","id":30928987,"diff_hunk":"@@ -8,196 +8,219 @@ learning about new modules and finding more specific documentation.\n For examples and help understanding how to use RAC, see the [README][] or\n the [Design Guidelines][].\n \n-## Streams\n+## Events\n \n-A **stream**, represented by the [RACStream][] abstract class, is any series of\n-object values.\n+An **event**, represented by the [Event][] class, is the formalized representation\n+of the fact that _something has happened_. In Reactive Cocoa, events are the center\n+piece of communication. An event might represent the press of a button, a piece \n+of information received from an API, the occurrence of an error or the completion \n+of a long running operation. A source generates events and sends them over a \n+[signal](#signals) to any number of [subscribers](#subscribers).\n \n-Values may be available immediately or in the future, but must be retrieved\n-sequentially. There is no way to retrieve the second value of a stream without\n-evaluating or waiting for the first value.\n-\n-Streams are [monads][]. Among other things, this allows complex operations to be\n-built on a few basic primitives (`-bind:` in particular). [RACStream][] also\n-implements the equivalent of the [Monoid][] and [MonadZip][] typeclasses from\n-[Haskell][].\n-\n-[RACStream][] isn't terribly useful on its own. Most streams are treated as\n-[signals](#signals) or [sequences](#sequences) instead.\n+An event has two types associated with it: the type of the value it holds when \n+everyting goes right, and the type of error it may hold in the case of a failure. \n+Additional to the _normal_ and the _failure_ case, an event can also represent \n+_completion_ and _interruption_.","path":"Documentation/FrameworkOverview.md","position":30,"original_position":30,"commit_id":"99ae3e3be9ec971c42381f1ab25386bf3b4b2120","original_commit_id":"99ae3e3be9ec971c42381f1ab25386bf3b4b2120","user":{"login":"iv-mexx","id":3407787,"avatar_url":"https://avatars.githubusercontent.com/u/3407787?v=3","gravatar_id":"","url":"https://api.github.com/users/iv-mexx","html_url":"https://github.com/iv-mexx","followers_url":"https://api.github.com/users/iv-mexx/followers","following_url":"https://api.github.com/users/iv-mexx/following{/other_user}","gists_url":"https://api.github.com/users/iv-mexx/gists{/gist_id}","starred_url":"https://api.github.com/users/iv-mexx/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/iv-mexx/subscriptions","organizations_url":"https://api.github.com/users/iv-mexx/orgs","repos_url":"https://api.github.com/users/iv-mexx/repos","events_url":"https://api.github.com/users/iv-mexx/events{/privacy}","received_events_url":"https://api.github.com/users/iv-mexx/received_events","type":"User","site_admin":false},"body":"Alright. I've cut out the _Terminating events are not included in the streams values, they must be \r\nhandeled specially._ sentences from the bulleted list here though and added it back to the Signals section because I felt that talking about the lifetime of signals, before really introducing them, was too early.","created_at":"2015-05-22T20:43:17Z","updated_at":"2015-05-22T20:43:17Z","html_url":"https://github.com/ReactiveCocoa/ReactiveCocoa/pull/2016#discussion_r30928987","pull_request_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/pulls/2016","_links":{"self":{"href":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/pulls/comments/30928987"},"html":{"href":"https://github.com/ReactiveCocoa/ReactiveCocoa/pull/2016#discussion_r30928987"},"pull_request":{"href":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/pulls/2016"}}},"pull_request":{"url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/pulls/2016","id":35594537,"html_url":"https://github.com/ReactiveCocoa/ReactiveCocoa/pull/2016","diff_url":"https://github.com/ReactiveCocoa/ReactiveCocoa/pull/2016.diff","patch_url":"https://github.com/ReactiveCocoa/ReactiveCocoa/pull/2016.patch","issue_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/issues/2016","number":2016,"state":"open","locked":false,"title":"Documentation: Framework Overview","user":{"login":"iv-mexx","id":3407787,"avatar_url":"https://avatars.githubusercontent.com/u/3407787?v=3","gravatar_id":"","url":"https://api.github.com/users/iv-mexx","html_url":"https://github.com/iv-mexx","followers_url":"https://api.github.com/users/iv-mexx/followers","following_url":"https://api.github.com/users/iv-mexx/following{/other_user}","gists_url":"https://api.github.com/users/iv-mexx/gists{/gist_id}","starred_url":"https://api.github.com/users/iv-mexx/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/iv-mexx/subscriptions","organizations_url":"https://api.github.com/users/iv-mexx/orgs","repos_url":"https://api.github.com/users/iv-mexx/repos","events_url":"https://api.github.com/users/iv-mexx/events{/privacy}","received_events_url":"https://api.github.com/users/iv-mexx/received_events","type":"User","site_admin":false},"body":"This is an attempt to update the __Framework Overview__ for RAC 3.0 #1485\r\nIts only a start, but I wanted to get some feedback before continuing.\r\n\r\nFirst off: I'm still new to RAC (i.e. to RAC 3.0). I have used RAC 2.x for a while now, but only for very simple stuff, mostly for KVO / to avoid using plain KVO. Now I'm trying to get more into RAC and thought I could maybe help a little bit while learning. I expect to get criticism on things I might have gotten wrong, but if it is too much work for you to correct my mistakes and you would rather have someone update the documentation who knows more about RAC - no problem, just let me know :stars: \r\n\r\n### Swift / OjbC or _old_ vs _new_\r\n\r\nThe most important question is how to deal with the Swift/ObjC split (as mentioned in #1483 ).\r\n\r\nThe [Changelog](https://github.com/ReactiveCocoa/ReactiveCocoa/blob/swift-development/CHANGELOG.md#using-startwithsignal-instead-of-multicasting) states that the ObjC API has almost not been touched, all RAC 3.0 changes are only additiv and 99% of RAC 2.x code will still work with RAC 3.0 without changes. \r\n\r\nHowever, also from the contents of the Changelog, I was under the impression that the updated documentation should concentrate on the new concepts of RAC 3.0. Anyway, I think the concepts should not be merged together like `Signal Producer (only Swift API): ...` because that would be confusing. Even more, because you could still use the complete _old_ RAC 2.x API in pure Swift without the new concepts (I think). \r\n\r\nWo what would be the best approach to solve this? Split the Documentation into _old_ and _new_: keep the existing documentation as is since its still valid plus add an updated version of the documentation that focuses only on the new approach. Call it _old_ / _new_, or call it _ObjC_ / _Swift_?\r\n\r\n### Work done so far\r\n\r\nAnyway, what I've done so far was under the assumption that the new docs should focus on the _new_/_Swift_ concepts of 3.0:\r\n\r\n* Remove the section about `Streams` (because its now covered by `Signal` completely) (?)\r\n* Update `Signal` section:\r\n  * briefly mention the concept of streams \r\n  * explain the concept of __hot__ signals (no side-effects, events sent regardless of subscribers) without mentioning __hot__ (_or should it be called hot here?_)\r\n  * add explanation of `interrupted` event\r\n* Add `SignalProducer` section:\r\n  * mostly taken from the [header documentation](https://github.com/ReactiveCocoa/ReactiveCocoa/blob/swift-development/ReactiveCocoa/Swift/SignalProducer.swift) but less specific (_no mention of types - should that be  mentioned here?_)\r\n  * explain the concept of __cold__ signals (performs side effects, perform work on demand), again without mentioning __cold__\r\n  * explain that disposables can be used to cancel the work\r\n\r\nFurthermore theres some `TODOs` added to the other remaining sections, for some sections its not clear to me if they should be removed or updated... Commenting on those TODOs would help me to know how to proceed. :bulb: \r\n\r\n","created_at":"2015-05-17T22:22:02Z","updated_at":"2015-05-22T20:43:17Z","closed_at":null,"merged_at":null,"merge_commit_sha":"18a04745c99357cfbd7b1b3ce4cd50852ad73fff","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/pulls/2016/commits","review_comments_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/pulls/2016/comments","review_comment_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/pulls/comments{/number}","comments_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/issues/2016/comments","statuses_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/statuses/99ae3e3be9ec971c42381f1ab25386bf3b4b2120","head":{"label":"iv-mexx:feature/documentation","ref":"feature/documentation","sha":"99ae3e3be9ec971c42381f1ab25386bf3b4b2120","user":{"login":"iv-mexx","id":3407787,"avatar_url":"https://avatars.githubusercontent.com/u/3407787?v=3","gravatar_id":"","url":"https://api.github.com/users/iv-mexx","html_url":"https://github.com/iv-mexx","followers_url":"https://api.github.com/users/iv-mexx/followers","following_url":"https://api.github.com/users/iv-mexx/following{/other_user}","gists_url":"https://api.github.com/users/iv-mexx/gists{/gist_id}","starred_url":"https://api.github.com/users/iv-mexx/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/iv-mexx/subscriptions","organizations_url":"https://api.github.com/users/iv-mexx/orgs","repos_url":"https://api.github.com/users/iv-mexx/repos","events_url":"https://api.github.com/users/iv-mexx/events{/privacy}","received_events_url":"https://api.github.com/users/iv-mexx/received_events","type":"User","site_admin":false},"repo":{"id":35776395,"name":"ReactiveCocoa","full_name":"iv-mexx/ReactiveCocoa","owner":{"login":"iv-mexx","id":3407787,"avatar_url":"https://avatars.githubusercontent.com/u/3407787?v=3","gravatar_id":"","url":"https://api.github.com/users/iv-mexx","html_url":"https://github.com/iv-mexx","followers_url":"https://api.github.com/users/iv-mexx/followers","following_url":"https://api.github.com/users/iv-mexx/following{/other_user}","gists_url":"https://api.github.com/users/iv-mexx/gists{/gist_id}","starred_url":"https://api.github.com/users/iv-mexx/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/iv-mexx/subscriptions","organizations_url":"https://api.github.com/users/iv-mexx/orgs","repos_url":"https://api.github.com/users/iv-mexx/repos","events_url":"https://api.github.com/users/iv-mexx/events{/privacy}","received_events_url":"https://api.github.com/users/iv-mexx/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/iv-mexx/ReactiveCocoa","description":"A framework for composing and transforming streams of values","fork":true,"url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa","forks_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/forks","keys_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/keys{/key_id}","collaborators_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/teams","hooks_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/hooks","issue_events_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/issues/events{/number}","events_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/events","assignees_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/assignees{/user}","branches_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/branches{/branch}","tags_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/tags","blobs_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/git/refs{/sha}","trees_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/git/trees{/sha}","statuses_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/statuses/{sha}","languages_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/languages","stargazers_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/stargazers","contributors_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/contributors","subscribers_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/subscribers","subscription_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/subscription","commits_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/commits{/sha}","git_commits_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/git/commits{/sha}","comments_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/comments{/number}","issue_comment_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/issues/comments{/number}","contents_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/contents/{+path}","compare_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/compare/{base}...{head}","merges_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/merges","archive_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/downloads","issues_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/issues{/number}","pulls_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/pulls{/number}","milestones_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/milestones{/number}","notifications_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/labels{/name}","releases_url":"https://api.github.com/repos/iv-mexx/ReactiveCocoa/releases{/id}","created_at":"2015-05-17T17:55:52Z","updated_at":"2015-05-17T17:55:55Z","pushed_at":"2015-05-21T20:40:07Z","git_url":"git://github.com/iv-mexx/ReactiveCocoa.git","ssh_url":"git@github.com:iv-mexx/ReactiveCocoa.git","clone_url":"https://github.com/iv-mexx/ReactiveCocoa.git","svn_url":"https://github.com/iv-mexx/ReactiveCocoa","homepage":"","size":13455,"stargazers_count":0,"watchers_count":0,"language":"Objective-C","has_issues":false,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"swift-development"}},"base":{"label":"ReactiveCocoa:swift-development","ref":"swift-development","sha":"08d561d09b43377dde28acc13393b8664105a410","user":{"login":"ReactiveCocoa","id":3422977,"avatar_url":"https://avatars.githubusercontent.com/u/3422977?v=3","gravatar_id":"","url":"https://api.github.com/users/ReactiveCocoa","html_url":"https://github.com/ReactiveCocoa","followers_url":"https://api.github.com/users/ReactiveCocoa/followers","following_url":"https://api.github.com/users/ReactiveCocoa/following{/other_user}","gists_url":"https://api.github.com/users/ReactiveCocoa/gists{/gist_id}","starred_url":"https://api.github.com/users/ReactiveCocoa/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ReactiveCocoa/subscriptions","organizations_url":"https://api.github.com/users/ReactiveCocoa/orgs","repos_url":"https://api.github.com/users/ReactiveCocoa/repos","events_url":"https://api.github.com/users/ReactiveCocoa/events{/privacy}","received_events_url":"https://api.github.com/users/ReactiveCocoa/received_events","type":"Organization","site_admin":false},"repo":{"id":3606624,"name":"ReactiveCocoa","full_name":"ReactiveCocoa/ReactiveCocoa","owner":{"login":"ReactiveCocoa","id":3422977,"avatar_url":"https://avatars.githubusercontent.com/u/3422977?v=3","gravatar_id":"","url":"https://api.github.com/users/ReactiveCocoa","html_url":"https://github.com/ReactiveCocoa","followers_url":"https://api.github.com/users/ReactiveCocoa/followers","following_url":"https://api.github.com/users/ReactiveCocoa/following{/other_user}","gists_url":"https://api.github.com/users/ReactiveCocoa/gists{/gist_id}","starred_url":"https://api.github.com/users/ReactiveCocoa/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ReactiveCocoa/subscriptions","organizations_url":"https://api.github.com/users/ReactiveCocoa/orgs","repos_url":"https://api.github.com/users/ReactiveCocoa/repos","events_url":"https://api.github.com/users/ReactiveCocoa/events{/privacy}","received_events_url":"https://api.github.com/users/ReactiveCocoa/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/ReactiveCocoa/ReactiveCocoa","description":"A framework for composing and transforming streams of values","fork":false,"url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa","forks_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/forks","keys_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/keys{/key_id}","collaborators_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/teams","hooks_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/hooks","issue_events_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/issues/events{/number}","events_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/events","assignees_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/assignees{/user}","branches_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/branches{/branch}","tags_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/tags","blobs_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/git/refs{/sha}","trees_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/git/trees{/sha}","statuses_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/statuses/{sha}","languages_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/languages","stargazers_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/stargazers","contributors_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/contributors","subscribers_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/subscribers","subscription_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/subscription","commits_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/commits{/sha}","git_commits_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/git/commits{/sha}","comments_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/comments{/number}","issue_comment_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/issues/comments{/number}","contents_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/contents/{+path}","compare_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/compare/{base}...{head}","merges_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/merges","archive_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/downloads","issues_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/issues{/number}","pulls_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/pulls{/number}","milestones_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/milestones{/number}","notifications_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/labels{/name}","releases_url":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/releases{/id}","created_at":"2012-03-02T22:11:24Z","updated_at":"2015-05-22T18:21:38Z","pushed_at":"2015-05-22T18:15:48Z","git_url":"git://github.com/ReactiveCocoa/ReactiveCocoa.git","ssh_url":"git@github.com:ReactiveCocoa/ReactiveCocoa.git","clone_url":"https://github.com/ReactiveCocoa/ReactiveCocoa.git","svn_url":"https://github.com/ReactiveCocoa/ReactiveCocoa","homepage":"","size":29689,"stargazers_count":8263,"watchers_count":8263,"language":"Objective-C","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":1244,"mirror_url":null,"open_issues_count":113,"forks":1244,"open_issues":113,"watchers":8263,"default_branch":"swift-development"}},"_links":{"self":{"href":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/pulls/2016"},"html":{"href":"https://github.com/ReactiveCocoa/ReactiveCocoa/pull/2016"},"issue":{"href":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/issues/2016"},"comments":{"href":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/issues/2016/comments"},"review_comments":{"href":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/pulls/2016/comments"},"review_comment":{"href":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/pulls/2016/commits"},"statuses":{"href":"https://api.github.com/repos/ReactiveCocoa/ReactiveCocoa/statuses/99ae3e3be9ec971c42381f1ab25386bf3b4b2120"}}}}