{"action":"created","comment":{"url":"https://api.github.com/repos/akka/akka/pulls/comments/30126997","id":30126997,"diff_hunk":"@@ -0,0 +1,224 @@\n+.. _Directives:\n+\n+Directives\n+==========\n+\n+A \"Directive\" is a small building block used for creating arbitrarily complex :ref:`route structures <Routes>`.\n+Akka HTTP already pre-defines a large number of directives and you can easily construct your own:\n+\n+.. toctree::\n+   :maxdepth: 1\n+\n+   alphabetically\n+   by-trait\n+   custom-directives\n+\n+\n+Basics\n+------\n+\n+Directives create :ref:`Routes`. To understand how directives work it is helpful to contrast them with the \"primitive\"\n+way of creating routes.\n+\n+Since ``Route`` is just a type alias for a function type ``Route`` instances can be written in any way in which function\n+instances can be written, e.g. as a function literal::\n+\n+    val route: Route = { ctx => ctx.complete(\"yeah\") }\n+\n+or shorter::\n+\n+    val route: Route = _.complete(\"yeah\")\n+\n+With the :ref:`-complete-` directive this becomes even shorter::\n+\n+    val route = complete(\"yeah\")\n+\n+These three ways of writing this ``Route`` are fully equivalent, the created ``route`` will behave identically in all\n+cases.\n+\n+Let's look at a slightly more complicated example to highlight one important point in particular.\n+Consider these two routes::\n+\n+    val a: Route = {\n+      println(\"MARK\")\n+      ctx => ctx.complete(\"yeah\")\n+    }\n+\n+    val b: Route = { ctx =>\n+      println(\"MARK\")\n+      ctx.complete(\"yeah\")\n+    }\n+\n+The difference between ``a`` and ``b`` is when the ``println`` statement is executed.\n+In the case of ``a`` it is executed *once*, when the route is constructed, whereas in the case of ``b`` it is executed\n+every time the route is *run*.\n+\n+Using the :ref:`-complete-` directive the same effects are achieved like this::","path":"akka-docs-dev/rst/scala/http/routing-dsl/directives/index.rst","position":56,"original_position":56,"commit_id":"81db5f8198581807493a9eaa3f49e168c8c5c4b8","original_commit_id":"81db5f8198581807493a9eaa3f49e168c8c5c4b8","user":{"login":"drewhk","id":932285,"avatar_url":"https://avatars.githubusercontent.com/u/932285?v=3","gravatar_id":"","url":"https://api.github.com/users/drewhk","html_url":"https://github.com/drewhk","followers_url":"https://api.github.com/users/drewhk/followers","following_url":"https://api.github.com/users/drewhk/following{/other_user}","gists_url":"https://api.github.com/users/drewhk/gists{/gist_id}","starred_url":"https://api.github.com/users/drewhk/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/drewhk/subscriptions","organizations_url":"https://api.github.com/users/drewhk/orgs","repos_url":"https://api.github.com/users/drewhk/repos","events_url":"https://api.github.com/users/drewhk/events{/privacy}","received_events_url":"https://api.github.com/users/drewhk/received_events","type":"User","site_admin":false},"body":"since I see the \"::\" repeating, is this some sort of RsT thing?","created_at":"2015-05-12T12:09:19Z","updated_at":"2015-05-12T12:09:19Z","html_url":"https://github.com/akka/akka/pull/17452#discussion_r30126997","pull_request_url":"https://api.github.com/repos/akka/akka/pulls/17452","_links":{"self":{"href":"https://api.github.com/repos/akka/akka/pulls/comments/30126997"},"html":{"href":"https://github.com/akka/akka/pull/17452#discussion_r30126997"},"pull_request":{"href":"https://api.github.com/repos/akka/akka/pulls/17452"}}},"pull_request":{"url":"https://api.github.com/repos/akka/akka/pulls/17452","id":35171492,"html_url":"https://github.com/akka/akka/pull/17452","diff_url":"https://github.com/akka/akka/pull/17452.diff","patch_url":"https://github.com/akka/akka/pull/17452.patch","issue_url":"https://api.github.com/repos/akka/akka/issues/17452","number":17452,"state":"open","locked":false,"title":"[Preview] WIP of coming docs for HTTP + smaller improvements","user":{"login":"sirthias","id":135347,"avatar_url":"https://avatars.githubusercontent.com/u/135347?v=3","gravatar_id":"","url":"https://api.github.com/users/sirthias","html_url":"https://github.com/sirthias","followers_url":"https://api.github.com/users/sirthias/followers","following_url":"https://api.github.com/users/sirthias/following{/other_user}","gists_url":"https://api.github.com/users/sirthias/gists{/gist_id}","starred_url":"https://api.github.com/users/sirthias/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/sirthias/subscriptions","organizations_url":"https://api.github.com/users/sirthias/orgs","repos_url":"https://api.github.com/users/sirthias/repos","events_url":"https://api.github.com/users/sirthias/events{/privacy}","received_events_url":"https://api.github.com/users/sirthias/received_events","type":"User","site_admin":false},"body":"[NOT FOR MERGE YET]\r\n\r\nThis is a WIP preview of the coming HTTP docs (several thousand lines!).\r\n\r\nAlong the way I came across a few mostly smaller improvement opportunities on APIs and internals (mostly in the Routing DSL) which I immediately seized.\r\n\r\nComplete:\r\n- Structure of HTTP docs on the Scala side done (with stubs for all content that is still missing).\r\n- Pages for all 128 (current count) directives present and properly linked up.\r\n- Bulk of non-directive content on client- and server-side done.\r\n\r\nStill missing:\r\n- \"Common\" sections on (un)marshalling, (de)compression and JSON/XML-support\r\n- Holes in directive docs\r\n- SSL and WebSocket chapters\r\n- Migration guide\r\n- Copy to the Java side\r\n\r\nCurrently the *akka-docs-dev* module doesn't compile because of not yet completed migration of directive examples from spray.\r\n\r\n/cc @jrudolph","created_at":"2015-05-11T21:28:07Z","updated_at":"2015-05-12T12:09:19Z","closed_at":null,"merged_at":null,"merge_commit_sha":"e3e2f411ec00974353e8e17cc97699c0e518782d","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/akka/akka/pulls/17452/commits","review_comments_url":"https://api.github.com/repos/akka/akka/pulls/17452/comments","review_comment_url":"https://api.github.com/repos/akka/akka/pulls/comments{/number}","comments_url":"https://api.github.com/repos/akka/akka/issues/17452/comments","statuses_url":"https://api.github.com/repos/akka/akka/statuses/81db5f8198581807493a9eaa3f49e168c8c5c4b8","head":{"label":"spray:wip-docs-mathias","ref":"wip-docs-mathias","sha":"81db5f8198581807493a9eaa3f49e168c8c5c4b8","user":{"login":"spray","id":688516,"avatar_url":"https://avatars.githubusercontent.com/u/688516?v=3","gravatar_id":"","url":"https://api.github.com/users/spray","html_url":"https://github.com/spray","followers_url":"https://api.github.com/users/spray/followers","following_url":"https://api.github.com/users/spray/following{/other_user}","gists_url":"https://api.github.com/users/spray/gists{/gist_id}","starred_url":"https://api.github.com/users/spray/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/spray/subscriptions","organizations_url":"https://api.github.com/users/spray/orgs","repos_url":"https://api.github.com/users/spray/repos","events_url":"https://api.github.com/users/spray/events{/privacy}","received_events_url":"https://api.github.com/users/spray/received_events","type":"Organization","site_admin":false},"repo":{"id":3809985,"name":"akka","full_name":"spray/akka","owner":{"login":"spray","id":688516,"avatar_url":"https://avatars.githubusercontent.com/u/688516?v=3","gravatar_id":"","url":"https://api.github.com/users/spray","html_url":"https://github.com/spray","followers_url":"https://api.github.com/users/spray/followers","following_url":"https://api.github.com/users/spray/following{/other_user}","gists_url":"https://api.github.com/users/spray/gists{/gist_id}","starred_url":"https://api.github.com/users/spray/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/spray/subscriptions","organizations_url":"https://api.github.com/users/spray/orgs","repos_url":"https://api.github.com/users/spray/repos","events_url":"https://api.github.com/users/spray/events{/privacy}","received_events_url":"https://api.github.com/users/spray/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/spray/akka","description":"Akka Project","fork":true,"url":"https://api.github.com/repos/spray/akka","forks_url":"https://api.github.com/repos/spray/akka/forks","keys_url":"https://api.github.com/repos/spray/akka/keys{/key_id}","collaborators_url":"https://api.github.com/repos/spray/akka/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/spray/akka/teams","hooks_url":"https://api.github.com/repos/spray/akka/hooks","issue_events_url":"https://api.github.com/repos/spray/akka/issues/events{/number}","events_url":"https://api.github.com/repos/spray/akka/events","assignees_url":"https://api.github.com/repos/spray/akka/assignees{/user}","branches_url":"https://api.github.com/repos/spray/akka/branches{/branch}","tags_url":"https://api.github.com/repos/spray/akka/tags","blobs_url":"https://api.github.com/repos/spray/akka/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/spray/akka/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/spray/akka/git/refs{/sha}","trees_url":"https://api.github.com/repos/spray/akka/git/trees{/sha}","statuses_url":"https://api.github.com/repos/spray/akka/statuses/{sha}","languages_url":"https://api.github.com/repos/spray/akka/languages","stargazers_url":"https://api.github.com/repos/spray/akka/stargazers","contributors_url":"https://api.github.com/repos/spray/akka/contributors","subscribers_url":"https://api.github.com/repos/spray/akka/subscribers","subscription_url":"https://api.github.com/repos/spray/akka/subscription","commits_url":"https://api.github.com/repos/spray/akka/commits{/sha}","git_commits_url":"https://api.github.com/repos/spray/akka/git/commits{/sha}","comments_url":"https://api.github.com/repos/spray/akka/comments{/number}","issue_comment_url":"https://api.github.com/repos/spray/akka/issues/comments{/number}","contents_url":"https://api.github.com/repos/spray/akka/contents/{+path}","compare_url":"https://api.github.com/repos/spray/akka/compare/{base}...{head}","merges_url":"https://api.github.com/repos/spray/akka/merges","archive_url":"https://api.github.com/repos/spray/akka/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/spray/akka/downloads","issues_url":"https://api.github.com/repos/spray/akka/issues{/number}","pulls_url":"https://api.github.com/repos/spray/akka/pulls{/number}","milestones_url":"https://api.github.com/repos/spray/akka/milestones{/number}","notifications_url":"https://api.github.com/repos/spray/akka/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/spray/akka/labels{/name}","releases_url":"https://api.github.com/repos/spray/akka/releases{/id}","created_at":"2012-03-23T15:57:31Z","updated_at":"2014-10-15T18:53:07Z","pushed_at":"2015-05-11T21:16:31Z","git_url":"git://github.com/spray/akka.git","ssh_url":"git@github.com:spray/akka.git","clone_url":"https://github.com/spray/akka.git","svn_url":"https://github.com/spray/akka","homepage":"http://akka.io","size":158241,"stargazers_count":7,"watchers_count":7,"language":"Scala","has_issues":false,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":1,"mirror_url":null,"open_issues_count":0,"forks":1,"open_issues":0,"watchers":7,"default_branch":"master"}},"base":{"label":"akka:release-2.3-dev","ref":"release-2.3-dev","sha":"baad36ef76f28b59bd1c22b4bf8162547100fe89","user":{"login":"akka","id":1496237,"avatar_url":"https://avatars.githubusercontent.com/u/1496237?v=3","gravatar_id":"","url":"https://api.github.com/users/akka","html_url":"https://github.com/akka","followers_url":"https://api.github.com/users/akka/followers","following_url":"https://api.github.com/users/akka/following{/other_user}","gists_url":"https://api.github.com/users/akka/gists{/gist_id}","starred_url":"https://api.github.com/users/akka/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/akka/subscriptions","organizations_url":"https://api.github.com/users/akka/orgs","repos_url":"https://api.github.com/users/akka/repos","events_url":"https://api.github.com/users/akka/events{/privacy}","received_events_url":"https://api.github.com/users/akka/received_events","type":"Organization","site_admin":false},"repo":{"id":130013,"name":"akka","full_name":"akka/akka","owner":{"login":"akka","id":1496237,"avatar_url":"https://avatars.githubusercontent.com/u/1496237?v=3","gravatar_id":"","url":"https://api.github.com/users/akka","html_url":"https://github.com/akka","followers_url":"https://api.github.com/users/akka/followers","following_url":"https://api.github.com/users/akka/following{/other_user}","gists_url":"https://api.github.com/users/akka/gists{/gist_id}","starred_url":"https://api.github.com/users/akka/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/akka/subscriptions","organizations_url":"https://api.github.com/users/akka/orgs","repos_url":"https://api.github.com/users/akka/repos","events_url":"https://api.github.com/users/akka/events{/privacy}","received_events_url":"https://api.github.com/users/akka/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/akka/akka","description":"Akka Project","fork":false,"url":"https://api.github.com/repos/akka/akka","forks_url":"https://api.github.com/repos/akka/akka/forks","keys_url":"https://api.github.com/repos/akka/akka/keys{/key_id}","collaborators_url":"https://api.github.com/repos/akka/akka/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/akka/akka/teams","hooks_url":"https://api.github.com/repos/akka/akka/hooks","issue_events_url":"https://api.github.com/repos/akka/akka/issues/events{/number}","events_url":"https://api.github.com/repos/akka/akka/events","assignees_url":"https://api.github.com/repos/akka/akka/assignees{/user}","branches_url":"https://api.github.com/repos/akka/akka/branches{/branch}","tags_url":"https://api.github.com/repos/akka/akka/tags","blobs_url":"https://api.github.com/repos/akka/akka/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/akka/akka/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/akka/akka/git/refs{/sha}","trees_url":"https://api.github.com/repos/akka/akka/git/trees{/sha}","statuses_url":"https://api.github.com/repos/akka/akka/statuses/{sha}","languages_url":"https://api.github.com/repos/akka/akka/languages","stargazers_url":"https://api.github.com/repos/akka/akka/stargazers","contributors_url":"https://api.github.com/repos/akka/akka/contributors","subscribers_url":"https://api.github.com/repos/akka/akka/subscribers","subscription_url":"https://api.github.com/repos/akka/akka/subscription","commits_url":"https://api.github.com/repos/akka/akka/commits{/sha}","git_commits_url":"https://api.github.com/repos/akka/akka/git/commits{/sha}","comments_url":"https://api.github.com/repos/akka/akka/comments{/number}","issue_comment_url":"https://api.github.com/repos/akka/akka/issues/comments{/number}","contents_url":"https://api.github.com/repos/akka/akka/contents/{+path}","compare_url":"https://api.github.com/repos/akka/akka/compare/{base}...{head}","merges_url":"https://api.github.com/repos/akka/akka/merges","archive_url":"https://api.github.com/repos/akka/akka/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/akka/akka/downloads","issues_url":"https://api.github.com/repos/akka/akka/issues{/number}","pulls_url":"https://api.github.com/repos/akka/akka/pulls{/number}","milestones_url":"https://api.github.com/repos/akka/akka/milestones{/number}","notifications_url":"https://api.github.com/repos/akka/akka/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/akka/akka/labels{/name}","releases_url":"https://api.github.com/repos/akka/akka/releases{/id}","created_at":"2009-02-16T12:51:54Z","updated_at":"2015-05-12T11:16:25Z","pushed_at":"2015-05-12T11:19:43Z","git_url":"git://github.com/akka/akka.git","ssh_url":"git@github.com:akka/akka.git","clone_url":"https://github.com/akka/akka.git","svn_url":"https://github.com/akka/akka","homepage":"http://akka.io","size":250801,"stargazers_count":3937,"watchers_count":3937,"language":"Scala","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":1133,"mirror_url":null,"open_issues_count":660,"forks":1133,"open_issues":660,"watchers":3937,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/akka/akka/pulls/17452"},"html":{"href":"https://github.com/akka/akka/pull/17452"},"issue":{"href":"https://api.github.com/repos/akka/akka/issues/17452"},"comments":{"href":"https://api.github.com/repos/akka/akka/issues/17452/comments"},"review_comments":{"href":"https://api.github.com/repos/akka/akka/pulls/17452/comments"},"review_comment":{"href":"https://api.github.com/repos/akka/akka/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/akka/akka/pulls/17452/commits"},"statuses":{"href":"https://api.github.com/repos/akka/akka/statuses/81db5f8198581807493a9eaa3f49e168c8c5c4b8"}}}}