{"action":"created","comment":{"url":"https://api.github.com/repos/ballerina-platform/ballerina-www/pulls/comments/184666164","pull_request_review_id":115910002,"id":184666164,"diff_hunk":"@@ -0,0 +1,190 @@\n+# How to Document Ballerina Code\n+\n+Ballerina has a built-in documentation framework named Docerina. The documentation framework allows you to write unstructured document with a bit of structure to enable generating HTML content as API documentation.\n+\n+Developers can write the documentation inline with the Ballerina source code using the lightweight markdown (https://en.wikipedia.org/wiki/Markdown) markup language. They can mark special occurrences such as parameters, return parameters, fields, endpoints within the documentation code using documentation attributes. Once the code is documented, developers can generate a basic HTML version of their ballerina packages using the `ballerina doc` command. You are encouraged to have your custom themes and styles, to have a better presentation of your Ballerina documentation. \n+\n+Ballerina design and usage is aligned with project and package semantics of Ballerina. You can generate documentation for the project packages using the ``ballerina doc`` command.\n+\n+\n+ ## Overview\n+* Ballerina programmers can place the documentation inline with the source code using documentation syntax.\n+* Ballerina records, type definitions, objects, global variables, annotations, endpoints can be documented using the documentation syntax.\n+* Fields, parameters, return parameters, endpoints can be marked using documentation attributes.\n+* HTML documents can be generated using the ``ballerina doc`` command for each Ballerina package and if you have custom handlebars templates, you can use them to generate the HTMLs.\n+\n+## Writing Ballerina Documentation\n+\n+Documentation is a first class syntax in the Ballerina language. ```documentation``` keyword followed by a curly braces denote a documentation node.\n+\n+```\n+documentation {\n+     …\n+     …\n+}\n+```\n+Within this ```documentation``` syntax, you can write your documentation in markdown markup language.\n+eg:\n+```\n+documentation {\n+   Provides the HTTP actions for interacting with an HTTP server. Apart from the standard \n+   HTTP methods, `forward()` and `execute()` functions are provided. More complex and specific \n+   endpoint types can be created by wrapping this generic ```HTTP``` actions implementation.\n+   ...\n+}\n+```\n+While you have the freedom to write any markdown document within the `documentation` syntax, Docerina encourages you to have some structure within the `documentation` syntax. Recommended structure is defined below;\n+\n+```\n+documentation {\n+     <description>\n+     <documentation_attribute>{{<documetable_object_name>}} <description> +\n+}\n+```\n+\n+## Supported Documentation Attributes\n+\n+`P` - Used to document a function input parameter\n+```\n+P{{id}} id of the employee\n+```\n+`R` - Used to document a function return parameter\n+```\n+R{{}} returns the name of the employee\n+```\n+`F` - Used to document a field of an object\n+```\n+F{{dob}} date of birth of the employee\n+```\n+`E` - Used to indicate an Endpoint object\n+```\n+E{{}}","path":"website/two-column-pages/docs/learn/how-to-document-ballerina-code.md","position":61,"original_position":61,"commit_id":"55c3b86cfa9c45e78671fc73d8fee60db260fdde","original_commit_id":"55c3b86cfa9c45e78671fc73d8fee60db260fdde","user":{"login":"samisawso2","id":7627249,"avatar_url":"https://avatars2.githubusercontent.com/u/7627249?v=4","gravatar_id":"","url":"https://api.github.com/users/samisawso2","html_url":"https://github.com/samisawso2","followers_url":"https://api.github.com/users/samisawso2/followers","following_url":"https://api.github.com/users/samisawso2/following{/other_user}","gists_url":"https://api.github.com/users/samisawso2/gists{/gist_id}","starred_url":"https://api.github.com/users/samisawso2/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/samisawso2/subscriptions","organizations_url":"https://api.github.com/users/samisawso2/orgs","repos_url":"https://api.github.com/users/samisawso2/repos","events_url":"https://api.github.com/users/samisawso2/events{/privacy}","received_events_url":"https://api.github.com/users/samisawso2/received_events","type":"User","site_admin":false},"body":"Can you give some meaningful doc text in here for endpoint sample? ","created_at":"2018-04-27T11:55:59Z","updated_at":"2018-04-27T11:56:43Z","html_url":"https://github.com/ballerina-platform/ballerina-www/pull/679#discussion_r184666164","pull_request_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/pulls/679","author_association":"CONTRIBUTOR","_links":{"self":{"href":"https://api.github.com/repos/ballerina-platform/ballerina-www/pulls/comments/184666164"},"html":{"href":"https://github.com/ballerina-platform/ballerina-www/pull/679#discussion_r184666164"},"pull_request":{"href":"https://api.github.com/repos/ballerina-platform/ballerina-www/pulls/679"}}},"pull_request":{"url":"https://api.github.com/repos/ballerina-platform/ballerina-www/pulls/679","id":184598726,"html_url":"https://github.com/ballerina-platform/ballerina-www/pull/679","diff_url":"https://github.com/ballerina-platform/ballerina-www/pull/679.diff","patch_url":"https://github.com/ballerina-platform/ballerina-www/pull/679.patch","issue_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/issues/679","number":679,"state":"open","locked":false,"title":"Create how-to-document-ballerina-code.md","user":{"login":"nirmal070125","id":413016,"avatar_url":"https://avatars0.githubusercontent.com/u/413016?v=4","gravatar_id":"","url":"https://api.github.com/users/nirmal070125","html_url":"https://github.com/nirmal070125","followers_url":"https://api.github.com/users/nirmal070125/followers","following_url":"https://api.github.com/users/nirmal070125/following{/other_user}","gists_url":"https://api.github.com/users/nirmal070125/gists{/gist_id}","starred_url":"https://api.github.com/users/nirmal070125/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/nirmal070125/subscriptions","organizations_url":"https://api.github.com/users/nirmal070125/orgs","repos_url":"https://api.github.com/users/nirmal070125/repos","events_url":"https://api.github.com/users/nirmal070125/events{/privacy}","received_events_url":"https://api.github.com/users/nirmal070125/received_events","type":"User","site_admin":false},"body":"## Purpose\r\n> Describe the problems, issues, or needs driving this feature/fix and include links to related issues in the following format: Resolves issue1, issue2, etc.\r\n\r\n## Goals\r\n> Describe the solutions that this feature/fix will introduce to resolve the problems described above\r\n\r\n## Approach\r\n> Describe how you are implementing the solutions. Include an animated GIF or screenshot if the change affects the UI (email documentation@wso2.com to review all UI text). Include a link to a Markdown file or Google doc if the feature write-up is too long to paste here.\r\n\r\n## User stories\r\n> Summary of user stories addressed by this change>\r\n\r\n## Release note\r\n> Brief description of the new feature or bug fix as it will appear in the release notes\r\n\r\n## Documentation\r\n> Link(s) to product documentation that addresses the changes of this PR. If no doc impact, enter “N/A” plus brief explanation of why there’s no doc impact\r\n\r\n## Training\r\n> Link to the PR for changes to the training content in https://github.com/wso2/WSO2-Training, if applicable\r\n\r\n## Certification\r\n> Type “Sent” when you have provided new/updated certification questions, plus four answers for each question (correct answer highlighted in bold), based on this change. Certification questions/answers should be sent to certification@wso2.com and NOT pasted in this PR. If there is no impact on certification exams, type “N/A” and explain why.\r\n\r\n## Marketing\r\n> Link to drafts of marketing content that will describe and promote this feature, including product page changes, technical articles, blog posts, videos, etc., if applicable\r\n\r\n## Automation tests\r\n - Unit tests \r\n   > Code coverage information\r\n - Integration tests\r\n   > Details about the test cases and coverage\r\n\r\n## Security checks\r\n - Followed secure coding standards in http://wso2.com/technical-reports/wso2-secure-engineering-guidelines? yes/no\r\n - Ran FindSecurityBugs plugin and verified report? yes/no\r\n - Confirmed that this PR doesn't commit any keys, passwords, tokens, usernames, or other secrets? yes/no\r\n\r\n## Samples\r\n> Provide high-level details about the samples related to this feature\r\n\r\n## Related PRs\r\n> List any other related PRs\r\n\r\n## Migrations (if applicable)\r\n> Describe migration steps and platforms on which migration has been tested\r\n\r\n## Test environment\r\n> List all JDK versions, operating systems, databases, and browser/versions on which this feature/fix was tested\r\n \r\n## Learning\r\n> Describe the research phase and any blog posts, patterns, libraries, or add-ons you used to solve the problem.","created_at":"2018-04-27T11:42:51Z","updated_at":"2018-04-27T11:56:43Z","closed_at":null,"merged_at":null,"merge_commit_sha":"4e53ea22ca13dc995e3c0ea569b153bb983508d5","assignee":null,"assignees":[],"requested_reviewers":[],"requested_teams":[],"labels":[{"id":915781999,"url":"https://api.github.com/repos/ballerina-platform/ballerina-www/labels/Content/New","name":"Content/New","color":"20b6b0","default":false}],"milestone":null,"commits_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/pulls/679/commits","review_comments_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/pulls/679/comments","review_comment_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/pulls/comments{/number}","comments_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/issues/679/comments","statuses_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/statuses/55c3b86cfa9c45e78671fc73d8fee60db260fdde","head":{"label":"nirmal070125:master","ref":"master","sha":"55c3b86cfa9c45e78671fc73d8fee60db260fdde","user":{"login":"nirmal070125","id":413016,"avatar_url":"https://avatars0.githubusercontent.com/u/413016?v=4","gravatar_id":"","url":"https://api.github.com/users/nirmal070125","html_url":"https://github.com/nirmal070125","followers_url":"https://api.github.com/users/nirmal070125/followers","following_url":"https://api.github.com/users/nirmal070125/following{/other_user}","gists_url":"https://api.github.com/users/nirmal070125/gists{/gist_id}","starred_url":"https://api.github.com/users/nirmal070125/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/nirmal070125/subscriptions","organizations_url":"https://api.github.com/users/nirmal070125/orgs","repos_url":"https://api.github.com/users/nirmal070125/repos","events_url":"https://api.github.com/users/nirmal070125/events{/privacy}","received_events_url":"https://api.github.com/users/nirmal070125/received_events","type":"User","site_admin":false},"repo":{"id":128717840,"name":"ballerina-www","full_name":"nirmal070125/ballerina-www","owner":{"login":"nirmal070125","id":413016,"avatar_url":"https://avatars0.githubusercontent.com/u/413016?v=4","gravatar_id":"","url":"https://api.github.com/users/nirmal070125","html_url":"https://github.com/nirmal070125","followers_url":"https://api.github.com/users/nirmal070125/followers","following_url":"https://api.github.com/users/nirmal070125/following{/other_user}","gists_url":"https://api.github.com/users/nirmal070125/gists{/gist_id}","starred_url":"https://api.github.com/users/nirmal070125/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/nirmal070125/subscriptions","organizations_url":"https://api.github.com/users/nirmal070125/orgs","repos_url":"https://api.github.com/users/nirmal070125/repos","events_url":"https://api.github.com/users/nirmal070125/events{/privacy}","received_events_url":"https://api.github.com/users/nirmal070125/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/nirmal070125/ballerina-www","description":null,"fork":true,"url":"https://api.github.com/repos/nirmal070125/ballerina-www","forks_url":"https://api.github.com/repos/nirmal070125/ballerina-www/forks","keys_url":"https://api.github.com/repos/nirmal070125/ballerina-www/keys{/key_id}","collaborators_url":"https://api.github.com/repos/nirmal070125/ballerina-www/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/nirmal070125/ballerina-www/teams","hooks_url":"https://api.github.com/repos/nirmal070125/ballerina-www/hooks","issue_events_url":"https://api.github.com/repos/nirmal070125/ballerina-www/issues/events{/number}","events_url":"https://api.github.com/repos/nirmal070125/ballerina-www/events","assignees_url":"https://api.github.com/repos/nirmal070125/ballerina-www/assignees{/user}","branches_url":"https://api.github.com/repos/nirmal070125/ballerina-www/branches{/branch}","tags_url":"https://api.github.com/repos/nirmal070125/ballerina-www/tags","blobs_url":"https://api.github.com/repos/nirmal070125/ballerina-www/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/nirmal070125/ballerina-www/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/nirmal070125/ballerina-www/git/refs{/sha}","trees_url":"https://api.github.com/repos/nirmal070125/ballerina-www/git/trees{/sha}","statuses_url":"https://api.github.com/repos/nirmal070125/ballerina-www/statuses/{sha}","languages_url":"https://api.github.com/repos/nirmal070125/ballerina-www/languages","stargazers_url":"https://api.github.com/repos/nirmal070125/ballerina-www/stargazers","contributors_url":"https://api.github.com/repos/nirmal070125/ballerina-www/contributors","subscribers_url":"https://api.github.com/repos/nirmal070125/ballerina-www/subscribers","subscription_url":"https://api.github.com/repos/nirmal070125/ballerina-www/subscription","commits_url":"https://api.github.com/repos/nirmal070125/ballerina-www/commits{/sha}","git_commits_url":"https://api.github.com/repos/nirmal070125/ballerina-www/git/commits{/sha}","comments_url":"https://api.github.com/repos/nirmal070125/ballerina-www/comments{/number}","issue_comment_url":"https://api.github.com/repos/nirmal070125/ballerina-www/issues/comments{/number}","contents_url":"https://api.github.com/repos/nirmal070125/ballerina-www/contents/{+path}","compare_url":"https://api.github.com/repos/nirmal070125/ballerina-www/compare/{base}...{head}","merges_url":"https://api.github.com/repos/nirmal070125/ballerina-www/merges","archive_url":"https://api.github.com/repos/nirmal070125/ballerina-www/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/nirmal070125/ballerina-www/downloads","issues_url":"https://api.github.com/repos/nirmal070125/ballerina-www/issues{/number}","pulls_url":"https://api.github.com/repos/nirmal070125/ballerina-www/pulls{/number}","milestones_url":"https://api.github.com/repos/nirmal070125/ballerina-www/milestones{/number}","notifications_url":"https://api.github.com/repos/nirmal070125/ballerina-www/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/nirmal070125/ballerina-www/labels{/name}","releases_url":"https://api.github.com/repos/nirmal070125/ballerina-www/releases{/id}","deployments_url":"https://api.github.com/repos/nirmal070125/ballerina-www/deployments","created_at":"2018-04-09T05:14:33Z","updated_at":"2018-04-27T11:42:42Z","pushed_at":"2018-04-27T11:42:40Z","git_url":"git://github.com/nirmal070125/ballerina-www.git","ssh_url":"git@github.com:nirmal070125/ballerina-www.git","clone_url":"https://github.com/nirmal070125/ballerina-www.git","svn_url":"https://github.com/nirmal070125/ballerina-www","homepage":null,"size":35843,"stargazers_count":0,"watchers_count":0,"language":"HTML","has_issues":false,"has_projects":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"archived":false,"open_issues_count":1,"license":{"key":"apache-2.0","name":"Apache License 2.0","spdx_id":"Apache-2.0","url":"https://api.github.com/licenses/apache-2.0"},"forks":0,"open_issues":1,"watchers":0,"default_branch":"master"}},"base":{"label":"ballerina-platform:master","ref":"master","sha":"41fddc49ba7cd054e68d277f873c1f81dc9cbafb","user":{"login":"ballerina-platform","id":34733518,"avatar_url":"https://avatars2.githubusercontent.com/u/34733518?v=4","gravatar_id":"","url":"https://api.github.com/users/ballerina-platform","html_url":"https://github.com/ballerina-platform","followers_url":"https://api.github.com/users/ballerina-platform/followers","following_url":"https://api.github.com/users/ballerina-platform/following{/other_user}","gists_url":"https://api.github.com/users/ballerina-platform/gists{/gist_id}","starred_url":"https://api.github.com/users/ballerina-platform/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ballerina-platform/subscriptions","organizations_url":"https://api.github.com/users/ballerina-platform/orgs","repos_url":"https://api.github.com/users/ballerina-platform/repos","events_url":"https://api.github.com/users/ballerina-platform/events{/privacy}","received_events_url":"https://api.github.com/users/ballerina-platform/received_events","type":"Organization","site_admin":false},"repo":{"id":124029242,"name":"ballerina-www","full_name":"ballerina-platform/ballerina-www","owner":{"login":"ballerina-platform","id":34733518,"avatar_url":"https://avatars2.githubusercontent.com/u/34733518?v=4","gravatar_id":"","url":"https://api.github.com/users/ballerina-platform","html_url":"https://github.com/ballerina-platform","followers_url":"https://api.github.com/users/ballerina-platform/followers","following_url":"https://api.github.com/users/ballerina-platform/following{/other_user}","gists_url":"https://api.github.com/users/ballerina-platform/gists{/gist_id}","starred_url":"https://api.github.com/users/ballerina-platform/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ballerina-platform/subscriptions","organizations_url":"https://api.github.com/users/ballerina-platform/orgs","repos_url":"https://api.github.com/users/ballerina-platform/repos","events_url":"https://api.github.com/users/ballerina-platform/events{/privacy}","received_events_url":"https://api.github.com/users/ballerina-platform/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/ballerina-platform/ballerina-www","description":null,"fork":false,"url":"https://api.github.com/repos/ballerina-platform/ballerina-www","forks_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/forks","keys_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/keys{/key_id}","collaborators_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/teams","hooks_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/hooks","issue_events_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/issues/events{/number}","events_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/events","assignees_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/assignees{/user}","branches_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/branches{/branch}","tags_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/tags","blobs_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/git/refs{/sha}","trees_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/git/trees{/sha}","statuses_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/statuses/{sha}","languages_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/languages","stargazers_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/stargazers","contributors_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/contributors","subscribers_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/subscribers","subscription_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/subscription","commits_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/commits{/sha}","git_commits_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/git/commits{/sha}","comments_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/comments{/number}","issue_comment_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/issues/comments{/number}","contents_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/contents/{+path}","compare_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/compare/{base}...{head}","merges_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/merges","archive_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/downloads","issues_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/issues{/number}","pulls_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/pulls{/number}","milestones_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/milestones{/number}","notifications_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/labels{/name}","releases_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/releases{/id}","deployments_url":"https://api.github.com/repos/ballerina-platform/ballerina-www/deployments","created_at":"2018-03-06T06:04:59Z","updated_at":"2018-04-27T11:49:28Z","pushed_at":"2018-04-27T11:49:26Z","git_url":"git://github.com/ballerina-platform/ballerina-www.git","ssh_url":"git@github.com:ballerina-platform/ballerina-www.git","clone_url":"https://github.com/ballerina-platform/ballerina-www.git","svn_url":"https://github.com/ballerina-platform/ballerina-www","homepage":null,"size":37916,"stargazers_count":0,"watchers_count":0,"language":"HTML","has_issues":true,"has_projects":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":28,"mirror_url":null,"archived":false,"open_issues_count":6,"license":{"key":"apache-2.0","name":"Apache License 2.0","spdx_id":"Apache-2.0","url":"https://api.github.com/licenses/apache-2.0"},"forks":28,"open_issues":6,"watchers":0,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/ballerina-platform/ballerina-www/pulls/679"},"html":{"href":"https://github.com/ballerina-platform/ballerina-www/pull/679"},"issue":{"href":"https://api.github.com/repos/ballerina-platform/ballerina-www/issues/679"},"comments":{"href":"https://api.github.com/repos/ballerina-platform/ballerina-www/issues/679/comments"},"review_comments":{"href":"https://api.github.com/repos/ballerina-platform/ballerina-www/pulls/679/comments"},"review_comment":{"href":"https://api.github.com/repos/ballerina-platform/ballerina-www/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/ballerina-platform/ballerina-www/pulls/679/commits"},"statuses":{"href":"https://api.github.com/repos/ballerina-platform/ballerina-www/statuses/55c3b86cfa9c45e78671fc73d8fee60db260fdde"}},"author_association":"CONTRIBUTOR"}}
{"actor":{"display_login":"samisawso2"}}