{"action":"created","issue":{"url":"https://api.github.com/repos/rust-lang-nursery/fmt-rfcs/issues/17","repository_url":"https://api.github.com/repos/rust-lang-nursery/fmt-rfcs","labels_url":"https://api.github.com/repos/rust-lang-nursery/fmt-rfcs/issues/17/labels{/name}","comments_url":"https://api.github.com/repos/rust-lang-nursery/fmt-rfcs/issues/17/comments","events_url":"https://api.github.com/repos/rust-lang-nursery/fmt-rfcs/issues/17/events","html_url":"https://github.com/rust-lang-nursery/fmt-rfcs/issues/17","id":179932918,"number":17,"title":"Comments","user":{"login":"nrc","id":762626,"avatar_url":"https://avatars.githubusercontent.com/u/762626?v=3","gravatar_id":"","url":"https://api.github.com/users/nrc","html_url":"https://github.com/nrc","followers_url":"https://api.github.com/users/nrc/followers","following_url":"https://api.github.com/users/nrc/following{/other_user}","gists_url":"https://api.github.com/users/nrc/gists{/gist_id}","starred_url":"https://api.github.com/users/nrc/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/nrc/subscriptions","organizations_url":"https://api.github.com/users/nrc/orgs","repos_url":"https://api.github.com/users/nrc/repos","events_url":"https://api.github.com/users/nrc/events{/privacy}","received_events_url":"https://api.github.com/users/nrc/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":10,"created_at":"2016-09-29T01:43:48Z","updated_at":"2016-09-29T19:14:03Z","closed_at":null,"body":"As well as specifying formatting for comments, we should decide on how much we expect Rustfmt to enforce (at the least, it cannot enforce correct grammar). My experience has been that re-formatting comments is almost impossible to get right. However, it is possible that we might be able formulate acceptable heuristics if we want to go down that road.\r\n\r\nThis one will need some fleshing out, but to start with:\r\n\r\n* Prefer `//` comments to `/* ... */` comments, use the latter only where there is code following on the same line.\r\n* Prefer `///` for doc comments, use `//!` only for module/crate-level docs. Avoid the other forms.\r\n* Comments should be complete sentences. Start with a capital letter, (usually) end with a period (`.`).\r\n* Have a single space after the comment sigils: `// A comment.` or `/// A doc comment.`\r\n* Comments should be indented with the code they are 'attached' to.\r\n* Comments should be kept within the 80 char margin (longer comments are harder to read).\r\n\r\nI do not believe we should get into what makes a comment good or bad, beyond its formatting.\r\n\r\nI propose that Rustfmt should basically avoid formatting comments. It can move comments to make them aligned with code and can add or remove whitespace around comments (if necessary, and I suspect it won't be). But Rustfmt should not change the actual text of the comment at all. Rustfmt should warn if a comment runs over the maximum width, but shouldn't attempt to fix that. Rustfmt should not change the style of the comment, nor the whitespace inside a comment.\r\n\r\nI'd be happy to have more sophisticated comment formatting (word-wrapping, etc.) behind an option, if that is of interest to users."},"comment":{"url":"https://api.github.com/repos/rust-lang-nursery/fmt-rfcs/issues/comments/250563410","html_url":"https://github.com/rust-lang-nursery/fmt-rfcs/issues/17#issuecomment-250563410","issue_url":"https://api.github.com/repos/rust-lang-nursery/fmt-rfcs/issues/17","id":250563410,"user":{"login":"nrc","id":762626,"avatar_url":"https://avatars.githubusercontent.com/u/762626?v=3","gravatar_id":"","url":"https://api.github.com/users/nrc","html_url":"https://github.com/nrc","followers_url":"https://api.github.com/users/nrc/followers","following_url":"https://api.github.com/users/nrc/following{/other_user}","gists_url":"https://api.github.com/users/nrc/gists{/gist_id}","starred_url":"https://api.github.com/users/nrc/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/nrc/subscriptions","organizations_url":"https://api.github.com/users/nrc/orgs","repos_url":"https://api.github.com/users/nrc/repos","events_url":"https://api.github.com/users/nrc/events{/privacy}","received_events_url":"https://api.github.com/users/nrc/received_events","type":"User","site_admin":false},"created_at":"2016-09-29T19:14:03Z","updated_at":"2016-09-29T19:14:03Z","body":"@skade \r\n\r\n> I would appreciate trimming of whitespace and word wrapping a lot\r\n\r\nUnfortunately this is the hardest bit because we need to be smart enough to guess when a comment is a code block and we should preserve whitespace and when it is not and we should wrap. We could trim trailing whitespace at the least, although I seem to remember even that can be significant for some systems :-(\r\n\r\n@pnkfelix \r\n\r\nYeah, the bullet points should be read as \"should\"s not \"must\"s and my current thinking is that they should not be enforced by tools. Rustfmt would have to move comments around, but that should probably be the limit of what it does."}}
{"actor":{"display_login":"nrc"}}