{"action":"created","issue":{"url":"https://api.github.com/repos/iTowns/itowns2/issues/314","repository_url":"https://api.github.com/repos/iTowns/itowns2","labels_url":"https://api.github.com/repos/iTowns/itowns2/issues/314/labels{/name}","comments_url":"https://api.github.com/repos/iTowns/itowns2/issues/314/comments","events_url":"https://api.github.com/repos/iTowns/itowns2/issues/314/events","html_url":"https://github.com/iTowns/itowns2/issues/314","id":231645757,"number":314,"title":"Documentation tool change proposal","user":{"login":"peppsac","id":2198295,"avatar_url":"https://avatars0.githubusercontent.com/u/2198295?v=3","gravatar_id":"","url":"https://api.github.com/users/peppsac","html_url":"https://github.com/peppsac","followers_url":"https://api.github.com/users/peppsac/followers","following_url":"https://api.github.com/users/peppsac/following{/other_user}","gists_url":"https://api.github.com/users/peppsac/gists{/gist_id}","starred_url":"https://api.github.com/users/peppsac/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/peppsac/subscriptions","organizations_url":"https://api.github.com/users/peppsac/orgs","repos_url":"https://api.github.com/users/peppsac/repos","events_url":"https://api.github.com/users/peppsac/events{/privacy}","received_events_url":"https://api.github.com/users/peppsac/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":8,"created_at":"2017-05-26T14:38:58Z","updated_at":"2017-05-31T09:47:09Z","closed_at":null,"body":"I wrote some documentation over the past few days and I feel that jsdoc isn't quite the tool I need.\r\n\r\nAs I may not be the only feeling this way I propose to discuss this issue here to settle the choice on our documentation tool.\r\n\r\nMy main issue regarding jsdoc is its special syntax: it clutters the code with information only useful to their tool (@param, @constructor, etc).\r\n\r\nI took a quick look at other tools, and found [docco](https://github.com/jashkenas/docco) which is really nice.\r\nBasically it puts no constraint on the programmer, and simply generate a documentation site from the comments in the code (see http://coffeescript.org/#literate for the inspiration).\r\n\r\nhttps://github.com/iTowns/itowns2/tree/documentation is my attempt at using docco for itowns. You can test by using the new command `npm run doc2` or you can see the result here: http://37.187.164.233/itowns-docs/\r\n\r\nA few notes:\r\n- I've modified 2 examples, so they are documented and functionnal on the API doc site\r\n- take a look at the source code of the commented files when using Docco (e.g https://github.com/iTowns/itowns2/blob/documentation/src/Core/View.js)\r\n- I modified docco to add a few short cut for our use case:\r\n   * internal autolink: if you write \"Camera*\" it will automatically insert a link to the documentation of Camera\r\n   * sidebar generation (as request by @vcoindet :)) and fuzzysearch (using implementation from https://blog.forrestthewoods.com/reverse-engineering-sublime-text-s-fuzzy-match-4cffeed33fdb#.7i6md382t)\r\n  * public function signature extraction\r\n- docco is a 200 lines project, so it's very easy to adapt :)\r\n  \r\nLet me know what you think :)\r\n"},"comment":{"url":"https://api.github.com/repos/iTowns/itowns2/issues/comments/305141290","html_url":"https://github.com/iTowns/itowns2/issues/314#issuecomment-305141290","issue_url":"https://api.github.com/repos/iTowns/itowns2/issues/314","id":305141290,"user":{"login":"tbroyer","id":173813,"avatar_url":"https://avatars2.githubusercontent.com/u/173813?v=3","gravatar_id":"","url":"https://api.github.com/users/tbroyer","html_url":"https://github.com/tbroyer","followers_url":"https://api.github.com/users/tbroyer/followers","following_url":"https://api.github.com/users/tbroyer/following{/other_user}","gists_url":"https://api.github.com/users/tbroyer/gists{/gist_id}","starred_url":"https://api.github.com/users/tbroyer/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tbroyer/subscriptions","organizations_url":"https://api.github.com/users/tbroyer/orgs","repos_url":"https://api.github.com/users/tbroyer/repos","events_url":"https://api.github.com/users/tbroyer/events{/privacy}","received_events_url":"https://api.github.com/users/tbroyer/received_events","type":"User","site_admin":false},"created_at":"2017-05-31T09:47:09Z","updated_at":"2017-05-31T09:47:09Z","body":"> as stated earlier we could simply adopt the `///` from Rust for documentation.\r\n\r\nI don't see where you proposed that.\r\n\r\n> Actually Rust documentation is a really good inspiration IMHO\r\n\r\nYes, except Rust is statically typed, so you don't need to document arguments if the type and name alone are self-sufficient (Go doesn't have structured comments either fwiw). JS is different, and jsdoc has the benefit of adding machine-readable type hints.\r\n\r\n> note that jsdoc is pretty inactive (no real activity since 2015 according to git logs).\r\n\r\nThere's esdoc and documentation.js too (among others); all relying on the same syntax.\r\n\r\n> jsdoc syntax vs markdown syntax : IMHO it's a big issue.\r\n\r\nIt's not really jsdoc vs markdown (jsdoc can use markdown too), it's more freestyle description vs. structured markup. The latter can be read by tools (for IDE inline help/completion, type checking, interop with other languages that compile down to JS), separates content from presentation (e.g. whether to present arguments as a list or a table), and can be checked/validated/linted (http://eslint.org/docs/rules/valid-jsdoc)\r\n\r\n> jsdoc is full of tags (`@Param`, `@constructor`, etc) which I consider being noise\r\n\r\nfwiw, I'd argue for omitting any tag that can be inferred statically from the code (e.g. `@class` and `@constructor` are redundant when using ES2015 classes), so most of the time you'd only use `@param` and `@returns` (if only to add type hints)\r\n\r\n> markdown on the other hand is easy to read / write: I think you can agree with me on this one\r\n\r\nIf we replace \"markdown\" in this sentence with \"freestyle documentation of arguments\", then I'm afraid I have to disagree.\r\n\r\nBut I think my point is more about: when there's a \"standard tool/syntax\" and you're bikeshedding about using something else (and in this case a \"custom\" tool), you're just wasting time and energy.\r\n**When there's a standard syntax, use it; you don't have to like it.**\r\n\r\n> By the way I'd love to hear from other dev\r\n\r\n:+1: "}}
{"actor":{"display_login":"tbroyer"}}