{"action":"created","comment":{"url":"https://api.github.com/repos/lift/framework/pulls/comments/24716940","id":24716940,"diff_hunk":"@@ -19,32 +19,97 @@ package json\n \n import scala.language.implicitConversions\n \n+/**\n+ * This object contains the abstract snytax tree (or AST) for working with JSON objects in lift-json.\n+ *\n+ * The purpose of the JsonAST is to represent and manipulate JSON by leveraging Scala language features like types,\n+ * case classes, etc. The AST should allow you to represent anything you could imagine from JSON land using the Scala\n+ * type system.\n+ *\n+ * Everything in the AST has a single root: JValue. A JValue could, quite literally, be anything. It could be an\n+ * an object (represented by [[JObject]]), a string ([[JString]]), a null ([[JNull]]), and so on. So, when constructing\n+ * a JSON object with the AST directly you might construct something like the following:\n+ *\n+ * {{{\n+ * JObject(JField(\"bacon\", JBool(true)) :: JField(\"spinach\", JBool(false)))\n+ * }}}\n+ *\n+ * Once serialized to the string representation of JSON you would end up with the following:\n+ *\n+ * {{{\n+ * {\n+ *   \"bacon\":true,\n+ *   \"spianch\":false\n+ * }\n+ * }}}\n+ */\n object JsonAST {\n   import scala.text.{Document, DocText}\n   import scala.text.Document._\n \n-  /** Concatenates a sequence of <code>JValue</code>s.\n-    * <p>\n-    * Example:<pre>\n+  /**\n+    * Concatenate a sequence of `JValue`s together.\n+    *\n+    * This would be useful in the event that you have a handful of `JValue` instances that need to be\n+    * smacked together into one unit.\n+    *\n+    * For example:\n+    *\n+    * {{{\n     * concat(JInt(1), JInt(2)) == JArray(List(JInt(1), JInt(2)))\n-    * </pre>\n+    * }}}\n+    *\n     */\n-  def concat(xs: JValue*) = xs.foldLeft(JNothing: JValue)(_ ++ _)\n+  def concat(values: JValue*) = values.foldLeft(JNothing: JValue)(_ ++ _)\n \n   object JValue extends Merge.Mergeable\n \n   /**\n-   * Data type for JSON AST.\n+   * The base type for all things that represent distinct JSON entities in the AST.\n+   *\n+   * Most members of the AST will extend this class. The one exception is [[JField]] which does not extend this class\n+   * because it really <em>can't</em> properly exist as a first-class citizen of JSON.\n    */\n   sealed abstract class JValue extends Diff.Diffable {\n     type Values\n \n-    /** XPath-like expression to query JSON fields by name. Matches only fields on\n-     * next level.\n-     * <p>\n-     * Example:<pre>\n-     * json \\ \"name\"\n-     * </pre>\n+    /**\n+     * Find a child of a `JObject` or a `JArray` of `JObject` by name, and return `JNothing` for anything else.\n+     *\n+     * This method is most useful if you have an object that you need to dig into in order to retrieve a specific value.\n+     * So, let's say that you had a JSON object that looked something like this:\n+     *\n+     * {{{\n+     * {\n+     *   \"name\": \"Joe\",\n+     *   \"profession\": \"Software Engineer\",\n+     *   \"catchphrase\": {\n+     *     \"name\": \"Alabama Cheer\",\n+     *     \"value\": \"Roll tide\"\n+     *   }\n+     * }\n+     * }}}\n+     *\n+     * If for some reason you're interested in taking a look at Joe's catchphrase, you can query it using the `\\` method\n+     * to find it like so:\n+     *\n+     * Example:\n+     *\n+     * {{{\n+     * > json \\ \"catchphrase\"\n+     * JObject(List(JField(\"name\", JString(\"Alabama Cheer\")), JField(\"value\", JString(\"Roll tide\"))))","path":"core/json/src/main/scala/net/liftweb/json/JsonAST.scala","position":101,"original_position":101,"commit_id":"967e180b1c21537e6b7ef360f116c50f8bccc90b","original_commit_id":"967e180b1c21537e6b7ef360f116c50f8bccc90b","user":{"login":"Shadowfiend","id":8245,"avatar_url":"https://avatars.githubusercontent.com/u/8245?v=3","gravatar_id":"","url":"https://api.github.com/users/Shadowfiend","html_url":"https://github.com/Shadowfiend","followers_url":"https://api.github.com/users/Shadowfiend/followers","following_url":"https://api.github.com/users/Shadowfiend/following{/other_user}","gists_url":"https://api.github.com/users/Shadowfiend/gists{/gist_id}","starred_url":"https://api.github.com/users/Shadowfiend/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Shadowfiend/subscriptions","organizations_url":"https://api.github.com/users/Shadowfiend/orgs","repos_url":"https://api.github.com/users/Shadowfiend/repos","events_url":"https://api.github.com/users/Shadowfiend/events{/privacy}","received_events_url":"https://api.github.com/users/Shadowfiend/received_events","type":"User","site_admin":false},"body":"Likewise, I've been including the `res0: `-type stuff the REPL adds for the same reason. Basically I copy-paste from the REPL :p ","created_at":"2015-02-14T20:10:21Z","updated_at":"2015-02-14T20:10:21Z","html_url":"https://github.com/lift/framework/pull/1683#discussion_r24716940","pull_request_url":"https://api.github.com/repos/lift/framework/pulls/1683","_links":{"self":{"href":"https://api.github.com/repos/lift/framework/pulls/comments/24716940"},"html":{"href":"https://github.com/lift/framework/pull/1683#discussion_r24716940"},"pull_request":{"href":"https://api.github.com/repos/lift/framework/pulls/1683"}}},"pull_request":{"url":"https://api.github.com/repos/lift/framework/pulls/1683","id":29322186,"html_url":"https://github.com/lift/framework/pull/1683","diff_url":"https://github.com/lift/framework/pull/1683.diff","patch_url":"https://github.com/lift/framework/pull/1683.patch","issue_url":"https://api.github.com/repos/lift/framework/issues/1683","number":1683,"state":"open","locked":false,"title":"Documentation Ape: Documentation updates to JsonAST and a few small code optimizations.","user":{"login":"farmdawgnation","id":620189,"avatar_url":"https://avatars.githubusercontent.com/u/620189?v=3","gravatar_id":"","url":"https://api.github.com/users/farmdawgnation","html_url":"https://github.com/farmdawgnation","followers_url":"https://api.github.com/users/farmdawgnation/followers","following_url":"https://api.github.com/users/farmdawgnation/following{/other_user}","gists_url":"https://api.github.com/users/farmdawgnation/gists{/gist_id}","starred_url":"https://api.github.com/users/farmdawgnation/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/farmdawgnation/subscriptions","organizations_url":"https://api.github.com/users/farmdawgnation/orgs","repos_url":"https://api.github.com/users/farmdawgnation/repos","events_url":"https://api.github.com/users/farmdawgnation/events{/privacy}","received_events_url":"https://api.github.com/users/farmdawgnation/received_events","type":"User","site_admin":false},"body":"![dawn-planet-apes-140709-700](https://cloud.githubusercontent.com/assets/620189/6200264/c7167af2-b43d-11e4-9402-13185aba91d3.jpg)\r\n\r\nThis PR does some updates to the documentation in JsonAST.\r\n\r\nML Thread about these changes: https://groups.google.com/d/msg/liftweb/b-xB7zVNzUQ/4z3485XEti0J","created_at":"2015-02-14T16:36:29Z","updated_at":"2015-02-14T20:10:21Z","closed_at":null,"merged_at":null,"merge_commit_sha":"02e15a98f32f148d59dad0ab6b61f4f66d6d59ff","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/lift/framework/pulls/1683/commits","review_comments_url":"https://api.github.com/repos/lift/framework/pulls/1683/comments","review_comment_url":"https://api.github.com/repos/lift/framework/pulls/comments/{number}","comments_url":"https://api.github.com/repos/lift/framework/issues/1683/comments","statuses_url":"https://api.github.com/repos/lift/framework/statuses/967e180b1c21537e6b7ef360f116c50f8bccc90b","head":{"label":"lift:documentation-ape","ref":"documentation-ape","sha":"967e180b1c21537e6b7ef360f116c50f8bccc90b","user":{"login":"lift","id":317975,"avatar_url":"https://avatars.githubusercontent.com/u/317975?v=3","gravatar_id":"","url":"https://api.github.com/users/lift","html_url":"https://github.com/lift","followers_url":"https://api.github.com/users/lift/followers","following_url":"https://api.github.com/users/lift/following{/other_user}","gists_url":"https://api.github.com/users/lift/gists{/gist_id}","starred_url":"https://api.github.com/users/lift/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/lift/subscriptions","organizations_url":"https://api.github.com/users/lift/orgs","repos_url":"https://api.github.com/users/lift/repos","events_url":"https://api.github.com/users/lift/events{/privacy}","received_events_url":"https://api.github.com/users/lift/received_events","type":"Organization","site_admin":false},"repo":{"id":1295197,"name":"framework","full_name":"lift/framework","owner":{"login":"lift","id":317975,"avatar_url":"https://avatars.githubusercontent.com/u/317975?v=3","gravatar_id":"","url":"https://api.github.com/users/lift","html_url":"https://github.com/lift","followers_url":"https://api.github.com/users/lift/followers","following_url":"https://api.github.com/users/lift/following{/other_user}","gists_url":"https://api.github.com/users/lift/gists{/gist_id}","starred_url":"https://api.github.com/users/lift/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/lift/subscriptions","organizations_url":"https://api.github.com/users/lift/orgs","repos_url":"https://api.github.com/users/lift/repos","events_url":"https://api.github.com/users/lift/events{/privacy}","received_events_url":"https://api.github.com/users/lift/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/lift/framework","description":"Lift Framework","fork":false,"url":"https://api.github.com/repos/lift/framework","forks_url":"https://api.github.com/repos/lift/framework/forks","keys_url":"https://api.github.com/repos/lift/framework/keys{/key_id}","collaborators_url":"https://api.github.com/repos/lift/framework/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/lift/framework/teams","hooks_url":"https://api.github.com/repos/lift/framework/hooks","issue_events_url":"https://api.github.com/repos/lift/framework/issues/events{/number}","events_url":"https://api.github.com/repos/lift/framework/events","assignees_url":"https://api.github.com/repos/lift/framework/assignees{/user}","branches_url":"https://api.github.com/repos/lift/framework/branches{/branch}","tags_url":"https://api.github.com/repos/lift/framework/tags","blobs_url":"https://api.github.com/repos/lift/framework/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/lift/framework/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/lift/framework/git/refs{/sha}","trees_url":"https://api.github.com/repos/lift/framework/git/trees{/sha}","statuses_url":"https://api.github.com/repos/lift/framework/statuses/{sha}","languages_url":"https://api.github.com/repos/lift/framework/languages","stargazers_url":"https://api.github.com/repos/lift/framework/stargazers","contributors_url":"https://api.github.com/repos/lift/framework/contributors","subscribers_url":"https://api.github.com/repos/lift/framework/subscribers","subscription_url":"https://api.github.com/repos/lift/framework/subscription","commits_url":"https://api.github.com/repos/lift/framework/commits{/sha}","git_commits_url":"https://api.github.com/repos/lift/framework/git/commits{/sha}","comments_url":"https://api.github.com/repos/lift/framework/comments{/number}","issue_comment_url":"https://api.github.com/repos/lift/framework/issues/comments/{number}","contents_url":"https://api.github.com/repos/lift/framework/contents/{+path}","compare_url":"https://api.github.com/repos/lift/framework/compare/{base}...{head}","merges_url":"https://api.github.com/repos/lift/framework/merges","archive_url":"https://api.github.com/repos/lift/framework/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/lift/framework/downloads","issues_url":"https://api.github.com/repos/lift/framework/issues{/number}","pulls_url":"https://api.github.com/repos/lift/framework/pulls{/number}","milestones_url":"https://api.github.com/repos/lift/framework/milestones{/number}","notifications_url":"https://api.github.com/repos/lift/framework/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/lift/framework/labels{/name}","releases_url":"https://api.github.com/repos/lift/framework/releases{/id}","created_at":"2011-01-26T13:25:28Z","updated_at":"2015-02-10T23:25:34Z","pushed_at":"2015-02-14T18:06:15Z","git_url":"git://github.com/lift/framework.git","ssh_url":"git@github.com:lift/framework.git","clone_url":"https://github.com/lift/framework.git","svn_url":"https://github.com/lift/framework","homepage":"http://liftweb.net","size":29578,"stargazers_count":852,"watchers_count":852,"language":"Scala","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":204,"mirror_url":null,"open_issues_count":135,"forks":204,"open_issues":135,"watchers":852,"default_branch":"master"}},"base":{"label":"lift:master","ref":"master","sha":"e2a53f0123dd784fc6f1d701d3b016855351e9bb","user":{"login":"lift","id":317975,"avatar_url":"https://avatars.githubusercontent.com/u/317975?v=3","gravatar_id":"","url":"https://api.github.com/users/lift","html_url":"https://github.com/lift","followers_url":"https://api.github.com/users/lift/followers","following_url":"https://api.github.com/users/lift/following{/other_user}","gists_url":"https://api.github.com/users/lift/gists{/gist_id}","starred_url":"https://api.github.com/users/lift/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/lift/subscriptions","organizations_url":"https://api.github.com/users/lift/orgs","repos_url":"https://api.github.com/users/lift/repos","events_url":"https://api.github.com/users/lift/events{/privacy}","received_events_url":"https://api.github.com/users/lift/received_events","type":"Organization","site_admin":false},"repo":{"id":1295197,"name":"framework","full_name":"lift/framework","owner":{"login":"lift","id":317975,"avatar_url":"https://avatars.githubusercontent.com/u/317975?v=3","gravatar_id":"","url":"https://api.github.com/users/lift","html_url":"https://github.com/lift","followers_url":"https://api.github.com/users/lift/followers","following_url":"https://api.github.com/users/lift/following{/other_user}","gists_url":"https://api.github.com/users/lift/gists{/gist_id}","starred_url":"https://api.github.com/users/lift/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/lift/subscriptions","organizations_url":"https://api.github.com/users/lift/orgs","repos_url":"https://api.github.com/users/lift/repos","events_url":"https://api.github.com/users/lift/events{/privacy}","received_events_url":"https://api.github.com/users/lift/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/lift/framework","description":"Lift Framework","fork":false,"url":"https://api.github.com/repos/lift/framework","forks_url":"https://api.github.com/repos/lift/framework/forks","keys_url":"https://api.github.com/repos/lift/framework/keys{/key_id}","collaborators_url":"https://api.github.com/repos/lift/framework/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/lift/framework/teams","hooks_url":"https://api.github.com/repos/lift/framework/hooks","issue_events_url":"https://api.github.com/repos/lift/framework/issues/events{/number}","events_url":"https://api.github.com/repos/lift/framework/events","assignees_url":"https://api.github.com/repos/lift/framework/assignees{/user}","branches_url":"https://api.github.com/repos/lift/framework/branches{/branch}","tags_url":"https://api.github.com/repos/lift/framework/tags","blobs_url":"https://api.github.com/repos/lift/framework/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/lift/framework/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/lift/framework/git/refs{/sha}","trees_url":"https://api.github.com/repos/lift/framework/git/trees{/sha}","statuses_url":"https://api.github.com/repos/lift/framework/statuses/{sha}","languages_url":"https://api.github.com/repos/lift/framework/languages","stargazers_url":"https://api.github.com/repos/lift/framework/stargazers","contributors_url":"https://api.github.com/repos/lift/framework/contributors","subscribers_url":"https://api.github.com/repos/lift/framework/subscribers","subscription_url":"https://api.github.com/repos/lift/framework/subscription","commits_url":"https://api.github.com/repos/lift/framework/commits{/sha}","git_commits_url":"https://api.github.com/repos/lift/framework/git/commits{/sha}","comments_url":"https://api.github.com/repos/lift/framework/comments{/number}","issue_comment_url":"https://api.github.com/repos/lift/framework/issues/comments/{number}","contents_url":"https://api.github.com/repos/lift/framework/contents/{+path}","compare_url":"https://api.github.com/repos/lift/framework/compare/{base}...{head}","merges_url":"https://api.github.com/repos/lift/framework/merges","archive_url":"https://api.github.com/repos/lift/framework/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/lift/framework/downloads","issues_url":"https://api.github.com/repos/lift/framework/issues{/number}","pulls_url":"https://api.github.com/repos/lift/framework/pulls{/number}","milestones_url":"https://api.github.com/repos/lift/framework/milestones{/number}","notifications_url":"https://api.github.com/repos/lift/framework/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/lift/framework/labels{/name}","releases_url":"https://api.github.com/repos/lift/framework/releases{/id}","created_at":"2011-01-26T13:25:28Z","updated_at":"2015-02-10T23:25:34Z","pushed_at":"2015-02-14T18:06:15Z","git_url":"git://github.com/lift/framework.git","ssh_url":"git@github.com:lift/framework.git","clone_url":"https://github.com/lift/framework.git","svn_url":"https://github.com/lift/framework","homepage":"http://liftweb.net","size":29578,"stargazers_count":852,"watchers_count":852,"language":"Scala","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":204,"mirror_url":null,"open_issues_count":135,"forks":204,"open_issues":135,"watchers":852,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/lift/framework/pulls/1683"},"html":{"href":"https://github.com/lift/framework/pull/1683"},"issue":{"href":"https://api.github.com/repos/lift/framework/issues/1683"},"comments":{"href":"https://api.github.com/repos/lift/framework/issues/1683/comments"},"review_comments":{"href":"https://api.github.com/repos/lift/framework/pulls/1683/comments"},"review_comment":{"href":"https://api.github.com/repos/lift/framework/pulls/comments/{number}"},"commits":{"href":"https://api.github.com/repos/lift/framework/pulls/1683/commits"},"statuses":{"href":"https://api.github.com/repos/lift/framework/statuses/967e180b1c21537e6b7ef360f116c50f8bccc90b"}}}}