{"action":"created","issue":{"url":"https://api.github.com/repos/supercollider/supercollider/issues/3630","repository_url":"https://api.github.com/repos/supercollider/supercollider","labels_url":"https://api.github.com/repos/supercollider/supercollider/issues/3630/labels{/name}","comments_url":"https://api.github.com/repos/supercollider/supercollider/issues/3630/comments","events_url":"https://api.github.com/repos/supercollider/supercollider/issues/3630/events","html_url":"https://github.com/supercollider/supercollider/issues/3630","id":311176968,"number":3630,"title":"FR: support inline documentation for classes","user":{"login":"aspiers","id":100738,"avatar_url":"https://avatars0.githubusercontent.com/u/100738?v=4","gravatar_id":"","url":"https://api.github.com/users/aspiers","html_url":"https://github.com/aspiers","followers_url":"https://api.github.com/users/aspiers/followers","following_url":"https://api.github.com/users/aspiers/following{/other_user}","gists_url":"https://api.github.com/users/aspiers/gists{/gist_id}","starred_url":"https://api.github.com/users/aspiers/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/aspiers/subscriptions","organizations_url":"https://api.github.com/users/aspiers/orgs","repos_url":"https://api.github.com/users/aspiers/repos","events_url":"https://api.github.com/users/aspiers/events{/privacy}","received_events_url":"https://api.github.com/users/aspiers/received_events","type":"User","site_admin":false},"labels":[{"id":4477105,"url":"https://api.github.com/repos/supercollider/supercollider/labels/comp:%20SCDoc","name":"comp: SCDoc","color":"CFFF7D","default":false},{"id":4413797,"url":"https://api.github.com/repos/supercollider/supercollider/labels/enhancement","name":"enhancement","color":"84b6eb","default":true}],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":10,"created_at":"2018-04-04T10:42:39Z","updated_at":"2018-04-08T10:13:47Z","closed_at":null,"author_association":"CONTRIBUTOR","body":"## Description\r\n\r\nCurrently documentation of any class lives in a separate `.schelp` file to the class itself.  I propose that `sclang` (and `scide` if necessary) be enhanced to also allow documentation embedded within classes.  Of course this should not prevent the documentation from being rendered in the same way it currently is, i.e. to HTML and to `scide`'s help browser.\r\n\r\nI know this is a big ask, so I merely ask that it be *considered* as a possible direction to take in the long-term.  I'm sure it would be a lot of work, so I'm not expecting it to happen any time soon ;-)\r\n\r\n## Rationale\r\n\r\n- Tighter coupling of documentation to code encourages better documentation:\r\n\r\n  When modifying a method, if the documentation is immediately above the code, it's a lot harder to ignore the docs and only modify the code.  Therefore the risk of forgetting to update documentation to match code changes is much lower.  This applies equally to the case where the developer thinks \"oh, I'll update the docs later in a separate commit\" and then never gets around to it.\r\n\r\n  Similarly, when adding a method to a class which is already documented, it's a lot harder to feel OK about skipping the documentation if it would be polluting an otherwise fully documented class with an undocumented method.  And of course, when deleting a method, it's a no brainer to delete the documentation which is right next to it, preventing accidental creation of orphaned documentation.\r\n\r\n- Inline documentation makes code easier to read\r\n\r\n  This one should be self-explanatory.  It's easier to understand code when the purpose of the method and the details of the arguments etc. are provided immediately above it.\r\n\r\n- Emulates best practice familiar to developers from other languages\r\n\r\n  Inline documentation is of course standard practice in many other languages.  This is why projects like [Doxygen](http://www.stack.nl/~dimitri/doxygen/) are so popular.\r\n\r\n## Out of scope\r\n\r\nNon-class documentation, such as guides, tutorials etc. would not need to be touched - they could still live in separate `.schelp` files as they do now."},"comment":{"url":"https://api.github.com/repos/supercollider/supercollider/issues/comments/379538359","html_url":"https://github.com/supercollider/supercollider/issues/3630#issuecomment-379538359","issue_url":"https://api.github.com/repos/supercollider/supercollider/issues/3630","id":379538359,"user":{"login":"muellmusik","id":1315053,"avatar_url":"https://avatars0.githubusercontent.com/u/1315053?v=4","gravatar_id":"","url":"https://api.github.com/users/muellmusik","html_url":"https://github.com/muellmusik","followers_url":"https://api.github.com/users/muellmusik/followers","following_url":"https://api.github.com/users/muellmusik/following{/other_user}","gists_url":"https://api.github.com/users/muellmusik/gists{/gist_id}","starred_url":"https://api.github.com/users/muellmusik/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/muellmusik/subscriptions","organizations_url":"https://api.github.com/users/muellmusik/orgs","repos_url":"https://api.github.com/users/muellmusik/repos","events_url":"https://api.github.com/users/muellmusik/events{/privacy}","received_events_url":"https://api.github.com/users/muellmusik/received_events","type":"User","site_admin":false},"created_at":"2018-04-08T10:13:47Z","updated_at":"2018-04-08T10:13:47Z","author_association":"CONTRIBUTOR","body":">I really wonder if our documentation would be as out of sync as it is if it were done in-source.\r\n\r\nOf course it would. The problem is not that people don’t know they need to document stuff or that everyone forgets. It’s a cultural one. Basically no changes should be merged without corresponding doc updates. This has to be the expected thing and devs need to buy into that. \r\n\r\nWe’ve made progress on the cultural front but there’s still a lot of old undocumented or out of sync stuff. I think a big push into fixing that would be far more productive in terms of getting stuff up to date than  reinventing the wheel, and I suspect partial reinvention would make that issue worse."}}
{"actor":{"display_login":"muellmusik"}}