{"action":"created","comment":{"url":"https://api.github.com/repos/apache/kafka/pulls/comments/60708548","id":60708548,"diff_hunk":"@@ -18,13 +18,22 @@\n package org.apache.kafka.streams.kstream;\n \n /**\n- * The Aggregator interface for aggregating values of the given key.\n+ * The {@link Aggregator} interface for aggregating values of the given key.\n  *\n  * @param <K>   key type\n  * @param <V>   original value type\n  * @param <T>   aggregate value type\n  */\n public interface Aggregator<K, V, T> {\n \n+    /**\n+     * Compute a new aggregate for the message with the given key and value and the current aggregate (ie,\n+     * {@link #apply(Object, Object, Object)} \"increments\" an aggregate with another message).","path":"streams/src/main/java/org/apache/kafka/streams/kstream/Aggregator.java","position":15,"original_position":15,"commit_id":"3dcbebb324777e5f6f5ea1df490f1af20c77038f","original_commit_id":"3dcbebb324777e5f6f5ea1df490f1af20c77038f","user":{"login":"mjsax","id":8959638,"avatar_url":"https://avatars.githubusercontent.com/u/8959638?v=3","gravatar_id":"","url":"https://api.github.com/users/mjsax","html_url":"https://github.com/mjsax","followers_url":"https://api.github.com/users/mjsax/followers","following_url":"https://api.github.com/users/mjsax/following{/other_user}","gists_url":"https://api.github.com/users/mjsax/gists{/gist_id}","starred_url":"https://api.github.com/users/mjsax/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mjsax/subscriptions","organizations_url":"https://api.github.com/users/mjsax/orgs","repos_url":"https://api.github.com/users/mjsax/repos","events_url":"https://api.github.com/users/mjsax/events{/privacy}","received_events_url":"https://api.github.com/users/mjsax/received_events","type":"User","site_admin":false},"body":"From my understanding, `apply` is called for each record to update the current (intermediate) agg-value. Something like this (assume the aggregation is a sum for input `3,2,8` and initial agg-value `0`)\r\n\r\n`apply(x, 3, 0) => 3`\r\n`apply(x, 2, 3) => 5`\r\n`apply(x, 8, 5) => 11`\r\n\r\nThus, the sum in incrementally build over all calls to `apply()`. In my understanding, increment does not mean `+1`, but has a more general meaning \"next step of the aggregation\" -- I also put it into quotes as a try to make this clear. But my understanding might not be common sense, and thus, \"increments\" might be miss leading.\r\n\r\nI thought it might be good to explain the user, that the computed/returned agg-result will be handed in as a parameter in the next call -- thus I put this additional explanation. If you think it is more miss leasing than helpful, we should just remove it. Or maybe you have a better idea to phrase this? (Or is my understanding of `apply()` wrong?)","created_at":"2016-04-22T08:48:40Z","updated_at":"2016-04-22T08:48:40Z","html_url":"https://github.com/apache/kafka/pull/1250#discussion_r60708548","pull_request_url":"https://api.github.com/repos/apache/kafka/pulls/1250","_links":{"self":{"href":"https://api.github.com/repos/apache/kafka/pulls/comments/60708548"},"html":{"href":"https://github.com/apache/kafka/pull/1250#discussion_r60708548"},"pull_request":{"href":"https://api.github.com/repos/apache/kafka/pulls/1250"}}},"pull_request":{"url":"https://api.github.com/repos/apache/kafka/pulls/1250","id":67345962,"html_url":"https://github.com/apache/kafka/pull/1250","diff_url":"https://github.com/apache/kafka/pull/1250.diff","patch_url":"https://github.com/apache/kafka/pull/1250.patch","issue_url":"https://api.github.com/repos/apache/kafka/issues/1250","number":1250,"state":"open","locked":false,"title":"KAFKA-3598: Improve JavaDoc of public API","user":{"login":"mjsax","id":8959638,"avatar_url":"https://avatars.githubusercontent.com/u/8959638?v=3","gravatar_id":"","url":"https://api.github.com/users/mjsax","html_url":"https://github.com/mjsax","followers_url":"https://api.github.com/users/mjsax/followers","following_url":"https://api.github.com/users/mjsax/following{/other_user}","gists_url":"https://api.github.com/users/mjsax/gists{/gist_id}","starred_url":"https://api.github.com/users/mjsax/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mjsax/subscriptions","organizations_url":"https://api.github.com/users/mjsax/orgs","repos_url":"https://api.github.com/users/mjsax/repos","events_url":"https://api.github.com/users/mjsax/events{/privacy}","received_events_url":"https://api.github.com/users/mjsax/received_events","type":"User","site_admin":false},"body":"","created_at":"2016-04-21T12:33:58Z","updated_at":"2016-04-22T08:48:40Z","closed_at":null,"merged_at":null,"merge_commit_sha":"1fc417f1f05dc4f26445d3ed75fa0592a1c1dbf2","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/apache/kafka/pulls/1250/commits","review_comments_url":"https://api.github.com/repos/apache/kafka/pulls/1250/comments","review_comment_url":"https://api.github.com/repos/apache/kafka/pulls/comments{/number}","comments_url":"https://api.github.com/repos/apache/kafka/issues/1250/comments","statuses_url":"https://api.github.com/repos/apache/kafka/statuses/3dcbebb324777e5f6f5ea1df490f1af20c77038f","head":{"label":"mjsax:JavaDoc-publicAPI","ref":"JavaDoc-publicAPI","sha":"3dcbebb324777e5f6f5ea1df490f1af20c77038f","user":{"login":"mjsax","id":8959638,"avatar_url":"https://avatars.githubusercontent.com/u/8959638?v=3","gravatar_id":"","url":"https://api.github.com/users/mjsax","html_url":"https://github.com/mjsax","followers_url":"https://api.github.com/users/mjsax/followers","following_url":"https://api.github.com/users/mjsax/following{/other_user}","gists_url":"https://api.github.com/users/mjsax/gists{/gist_id}","starred_url":"https://api.github.com/users/mjsax/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mjsax/subscriptions","organizations_url":"https://api.github.com/users/mjsax/orgs","repos_url":"https://api.github.com/users/mjsax/repos","events_url":"https://api.github.com/users/mjsax/events{/privacy}","received_events_url":"https://api.github.com/users/mjsax/received_events","type":"User","site_admin":false},"repo":{"id":50839421,"name":"kafka","full_name":"mjsax/kafka","owner":{"login":"mjsax","id":8959638,"avatar_url":"https://avatars.githubusercontent.com/u/8959638?v=3","gravatar_id":"","url":"https://api.github.com/users/mjsax","html_url":"https://github.com/mjsax","followers_url":"https://api.github.com/users/mjsax/followers","following_url":"https://api.github.com/users/mjsax/following{/other_user}","gists_url":"https://api.github.com/users/mjsax/gists{/gist_id}","starred_url":"https://api.github.com/users/mjsax/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mjsax/subscriptions","organizations_url":"https://api.github.com/users/mjsax/orgs","repos_url":"https://api.github.com/users/mjsax/repos","events_url":"https://api.github.com/users/mjsax/events{/privacy}","received_events_url":"https://api.github.com/users/mjsax/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/mjsax/kafka","description":"Mirror of Apache Kafka","fork":true,"url":"https://api.github.com/repos/mjsax/kafka","forks_url":"https://api.github.com/repos/mjsax/kafka/forks","keys_url":"https://api.github.com/repos/mjsax/kafka/keys{/key_id}","collaborators_url":"https://api.github.com/repos/mjsax/kafka/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/mjsax/kafka/teams","hooks_url":"https://api.github.com/repos/mjsax/kafka/hooks","issue_events_url":"https://api.github.com/repos/mjsax/kafka/issues/events{/number}","events_url":"https://api.github.com/repos/mjsax/kafka/events","assignees_url":"https://api.github.com/repos/mjsax/kafka/assignees{/user}","branches_url":"https://api.github.com/repos/mjsax/kafka/branches{/branch}","tags_url":"https://api.github.com/repos/mjsax/kafka/tags","blobs_url":"https://api.github.com/repos/mjsax/kafka/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/mjsax/kafka/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/mjsax/kafka/git/refs{/sha}","trees_url":"https://api.github.com/repos/mjsax/kafka/git/trees{/sha}","statuses_url":"https://api.github.com/repos/mjsax/kafka/statuses/{sha}","languages_url":"https://api.github.com/repos/mjsax/kafka/languages","stargazers_url":"https://api.github.com/repos/mjsax/kafka/stargazers","contributors_url":"https://api.github.com/repos/mjsax/kafka/contributors","subscribers_url":"https://api.github.com/repos/mjsax/kafka/subscribers","subscription_url":"https://api.github.com/repos/mjsax/kafka/subscription","commits_url":"https://api.github.com/repos/mjsax/kafka/commits{/sha}","git_commits_url":"https://api.github.com/repos/mjsax/kafka/git/commits{/sha}","comments_url":"https://api.github.com/repos/mjsax/kafka/comments{/number}","issue_comment_url":"https://api.github.com/repos/mjsax/kafka/issues/comments{/number}","contents_url":"https://api.github.com/repos/mjsax/kafka/contents/{+path}","compare_url":"https://api.github.com/repos/mjsax/kafka/compare/{base}...{head}","merges_url":"https://api.github.com/repos/mjsax/kafka/merges","archive_url":"https://api.github.com/repos/mjsax/kafka/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/mjsax/kafka/downloads","issues_url":"https://api.github.com/repos/mjsax/kafka/issues{/number}","pulls_url":"https://api.github.com/repos/mjsax/kafka/pulls{/number}","milestones_url":"https://api.github.com/repos/mjsax/kafka/milestones{/number}","notifications_url":"https://api.github.com/repos/mjsax/kafka/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/mjsax/kafka/labels{/name}","releases_url":"https://api.github.com/repos/mjsax/kafka/releases{/id}","deployments_url":"https://api.github.com/repos/mjsax/kafka/deployments","created_at":"2016-02-01T12:57:30Z","updated_at":"2016-02-01T12:57:34Z","pushed_at":"2016-04-21T12:51:18Z","git_url":"git://github.com/mjsax/kafka.git","ssh_url":"git@github.com:mjsax/kafka.git","clone_url":"https://github.com/mjsax/kafka.git","svn_url":"https://github.com/mjsax/kafka","homepage":null,"size":29674,"stargazers_count":0,"watchers_count":0,"language":"Java","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":"trunk"}},"base":{"label":"apache:trunk","ref":"trunk","sha":"9d71489ff0e62fd1897c7a6f54671673db7b37b8","user":{"login":"apache","id":47359,"avatar_url":"https://avatars.githubusercontent.com/u/47359?v=3","gravatar_id":"","url":"https://api.github.com/users/apache","html_url":"https://github.com/apache","followers_url":"https://api.github.com/users/apache/followers","following_url":"https://api.github.com/users/apache/following{/other_user}","gists_url":"https://api.github.com/users/apache/gists{/gist_id}","starred_url":"https://api.github.com/users/apache/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/apache/subscriptions","organizations_url":"https://api.github.com/users/apache/orgs","repos_url":"https://api.github.com/users/apache/repos","events_url":"https://api.github.com/users/apache/events{/privacy}","received_events_url":"https://api.github.com/users/apache/received_events","type":"Organization","site_admin":false},"repo":{"id":2211243,"name":"kafka","full_name":"apache/kafka","owner":{"login":"apache","id":47359,"avatar_url":"https://avatars.githubusercontent.com/u/47359?v=3","gravatar_id":"","url":"https://api.github.com/users/apache","html_url":"https://github.com/apache","followers_url":"https://api.github.com/users/apache/followers","following_url":"https://api.github.com/users/apache/following{/other_user}","gists_url":"https://api.github.com/users/apache/gists{/gist_id}","starred_url":"https://api.github.com/users/apache/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/apache/subscriptions","organizations_url":"https://api.github.com/users/apache/orgs","repos_url":"https://api.github.com/users/apache/repos","events_url":"https://api.github.com/users/apache/events{/privacy}","received_events_url":"https://api.github.com/users/apache/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/apache/kafka","description":"Mirror of Apache Kafka","fork":false,"url":"https://api.github.com/repos/apache/kafka","forks_url":"https://api.github.com/repos/apache/kafka/forks","keys_url":"https://api.github.com/repos/apache/kafka/keys{/key_id}","collaborators_url":"https://api.github.com/repos/apache/kafka/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/apache/kafka/teams","hooks_url":"https://api.github.com/repos/apache/kafka/hooks","issue_events_url":"https://api.github.com/repos/apache/kafka/issues/events{/number}","events_url":"https://api.github.com/repos/apache/kafka/events","assignees_url":"https://api.github.com/repos/apache/kafka/assignees{/user}","branches_url":"https://api.github.com/repos/apache/kafka/branches{/branch}","tags_url":"https://api.github.com/repos/apache/kafka/tags","blobs_url":"https://api.github.com/repos/apache/kafka/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/apache/kafka/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/apache/kafka/git/refs{/sha}","trees_url":"https://api.github.com/repos/apache/kafka/git/trees{/sha}","statuses_url":"https://api.github.com/repos/apache/kafka/statuses/{sha}","languages_url":"https://api.github.com/repos/apache/kafka/languages","stargazers_url":"https://api.github.com/repos/apache/kafka/stargazers","contributors_url":"https://api.github.com/repos/apache/kafka/contributors","subscribers_url":"https://api.github.com/repos/apache/kafka/subscribers","subscription_url":"https://api.github.com/repos/apache/kafka/subscription","commits_url":"https://api.github.com/repos/apache/kafka/commits{/sha}","git_commits_url":"https://api.github.com/repos/apache/kafka/git/commits{/sha}","comments_url":"https://api.github.com/repos/apache/kafka/comments{/number}","issue_comment_url":"https://api.github.com/repos/apache/kafka/issues/comments{/number}","contents_url":"https://api.github.com/repos/apache/kafka/contents/{+path}","compare_url":"https://api.github.com/repos/apache/kafka/compare/{base}...{head}","merges_url":"https://api.github.com/repos/apache/kafka/merges","archive_url":"https://api.github.com/repos/apache/kafka/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/apache/kafka/downloads","issues_url":"https://api.github.com/repos/apache/kafka/issues{/number}","pulls_url":"https://api.github.com/repos/apache/kafka/pulls{/number}","milestones_url":"https://api.github.com/repos/apache/kafka/milestones{/number}","notifications_url":"https://api.github.com/repos/apache/kafka/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/apache/kafka/labels{/name}","releases_url":"https://api.github.com/repos/apache/kafka/releases{/id}","deployments_url":"https://api.github.com/repos/apache/kafka/deployments","created_at":"2011-08-15T18:06:16Z","updated_at":"2016-04-22T08:26:29Z","pushed_at":"2016-04-22T08:39:22Z","git_url":"git://github.com/apache/kafka.git","ssh_url":"git@github.com:apache/kafka.git","clone_url":"https://github.com/apache/kafka.git","svn_url":"https://github.com/apache/kafka","homepage":null,"size":39847,"stargazers_count":2984,"watchers_count":2984,"language":"Java","has_issues":false,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":1791,"mirror_url":"git://git.apache.org/kafka.git","open_issues_count":185,"forks":1791,"open_issues":185,"watchers":2984,"default_branch":"trunk"}},"_links":{"self":{"href":"https://api.github.com/repos/apache/kafka/pulls/1250"},"html":{"href":"https://github.com/apache/kafka/pull/1250"},"issue":{"href":"https://api.github.com/repos/apache/kafka/issues/1250"},"comments":{"href":"https://api.github.com/repos/apache/kafka/issues/1250/comments"},"review_comments":{"href":"https://api.github.com/repos/apache/kafka/pulls/1250/comments"},"review_comment":{"href":"https://api.github.com/repos/apache/kafka/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/apache/kafka/pulls/1250/commits"},"statuses":{"href":"https://api.github.com/repos/apache/kafka/statuses/3dcbebb324777e5f6f5ea1df490f1af20c77038f"}}}}