{"action":"created","issue":{"url":"https://api.github.com/repos/basiljs/basil.js/issues/270","repository_url":"https://api.github.com/repos/basiljs/basil.js","labels_url":"https://api.github.com/repos/basiljs/basil.js/issues/270/labels{/name}","comments_url":"https://api.github.com/repos/basiljs/basil.js/issues/270/comments","events_url":"https://api.github.com/repos/basiljs/basil.js/issues/270/events","html_url":"https://github.com/basiljs/basil.js/pull/270","id":314103744,"number":270,"title":"Consistent formatting of jsdocs comments","user":{"login":"trych","id":9803905,"avatar_url":"https://avatars2.githubusercontent.com/u/9803905?v=4","gravatar_id":"","url":"https://api.github.com/users/trych","html_url":"https://github.com/trych","followers_url":"https://api.github.com/users/trych/followers","following_url":"https://api.github.com/users/trych/following{/other_user}","gists_url":"https://api.github.com/users/trych/gists{/gist_id}","starred_url":"https://api.github.com/users/trych/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/trych/subscriptions","organizations_url":"https://api.github.com/users/trych/orgs","repos_url":"https://api.github.com/users/trych/repos","events_url":"https://api.github.com/users/trych/events{/privacy}","received_events_url":"https://api.github.com/users/trych/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":2,"created_at":"2018-04-13T13:17:52Z","updated_at":"2018-04-14T09:10:53Z","closed_at":null,"author_association":"CONTRIBUTOR","pull_request":{"url":"https://api.github.com/repos/basiljs/basil.js/pulls/270","html_url":"https://github.com/basiljs/basil.js/pull/270","diff_url":"https://github.com/basiljs/basil.js/pull/270.diff","patch_url":"https://github.com/basiljs/basil.js/pull/270.patch"},"body":"This makes the formatting of all jsdocs inline documentation consistent and therefore cleans it up considerably and prepares the code for the restructuring of categories. After quite a bit of research and testing around, I came up with a formatting style that looks clean, is maintainable and works with the doc generation (once we have the markdown rendering in place).\r\n\r\nHere is a before/after of the `margins()` function\r\n\r\nBefore\r\n```js\r\n/**\r\n * Sets the margins of a given page. If 1 value is given, all 4 sides are set equally. If 4 values are given, the current page will be adjusted. Adding a 5th value will set the margin of a given page. Calling the function without any values, will return the margins for the current page.\r\n *\r\n * @cat Document\r\n * @subcat Page\r\n * @method margins\r\n * @param {Number} [top] Top margin or all if only one.\r\n * @param {Number} [right] Right margin.\r\n * @param {Number} [bottom] Bottom margin.\r\n * @param {Number} [left] Left margin.\r\n * @param {Number} [pageNumber] Sets margins to selected page, currentPage() if left blank.\r\n * @return {Object} Current page margins with the properties: top, right, bottom, left.\r\n */\r\n```\r\n\r\nAfter\r\n```js\r\n/**\r\n * @description Sets the margins of a given page. If 1 value is given, all 4\r\n *          sides are set equally. If 4 values are given, the current page will\r\n *          be adjusted. Adding a 5th value will set the margin of a given page.\r\n *          Calling the function without any values, will return the margins for\r\n *          the current page.\r\n *\r\n * @cat     Document\r\n * @subcat  Page\r\n * @method  margins\r\n *\r\n * @param   {Number} [top] Top margin or all if only one.\r\n * @param   {Number} [right] Right margin.\r\n * @param   {Number} [bottom] Bottom margin.\r\n * @param   {Number} [left] Left margin.\r\n * @param   {Number} [pageNumber] Sets margins to selected page, currentPage()\r\n *          if left blank.\r\n * @return  {Object} Current page margins with the properties: `top`, `right`,\r\n *          `bottom`, `left`.\r\n */\r\n```\r\n\r\nAs you can see, this now also strictly stays within the 80-characters line limit to be better readable in most editors.\r\n\r\nThe syntax looks like this now:\r\n```js\r\n/**\r\n * @description The description of the method. If the description is longer, it\r\n *          wraps around to an indentation value that aligns with other\r\n *          information below.\r\n *\r\n * @cat     Category\r\n * @subcat  Sub-Category\r\n * @method  methodName\r\n *\r\n * @param   {Type} name A parameter.\r\n * @param   {Type} name A parameter with a description that is long enough that\r\n *          it wraps into the next line.\r\n * @param   {Type} [name] An optional parameter.\r\n * @return  {Type} Description of the return value. This also wraps into the\r\n *          next line if the description is long enough.\r\n *          \r\n * @example <caption>How to use this function</caption>\r\n * var foo = methodName(); // code lines must not use indentation\r\n */\r\n```\r\n\r\nAll methods have been changed to adhere to this new syntax. Markdown was added for inline code snippets and for lists."},"comment":{"url":"https://api.github.com/repos/basiljs/basil.js/issues/comments/381315489","html_url":"https://github.com/basiljs/basil.js/pull/270#issuecomment-381315489","issue_url":"https://api.github.com/repos/basiljs/basil.js/issues/270","id":381315489,"user":{"login":"trych","id":9803905,"avatar_url":"https://avatars2.githubusercontent.com/u/9803905?v=4","gravatar_id":"","url":"https://api.github.com/users/trych","html_url":"https://github.com/trych","followers_url":"https://api.github.com/users/trych/followers","following_url":"https://api.github.com/users/trych/following{/other_user}","gists_url":"https://api.github.com/users/trych/gists{/gist_id}","starred_url":"https://api.github.com/users/trych/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/trych/subscriptions","organizations_url":"https://api.github.com/users/trych/orgs","repos_url":"https://api.github.com/users/trych/repos","events_url":"https://api.github.com/users/trych/events{/privacy}","received_events_url":"https://api.github.com/users/trych/received_events","type":"User","site_admin":false},"created_at":"2018-04-14T09:10:53Z","updated_at":"2018-04-14T09:10:53Z","author_association":"CONTRIBUTOR","body":"It's not not interpreted as markdown code blocks during parsing, I tested this quite intensely. It parses just fine. "}}
{"actor":{"display_login":"trych"}}