{"action":"created","issue":{"url":"https://api.github.com/repos/dotnet/roslyn/issues/85","labels_url":"https://api.github.com/repos/dotnet/roslyn/issues/85/labels{/name}","comments_url":"https://api.github.com/repos/dotnet/roslyn/issues/85/comments","events_url":"https://api.github.com/repos/dotnet/roslyn/issues/85/events","html_url":"https://github.com/dotnet/roslyn/issues/85","id":55632286,"number":85,"title":"Feature Request: Lighter syntax for doc comments","user":{"login":"MgSam","id":1965570,"avatar_url":"https://avatars.githubusercontent.com/u/1965570?v=3","gravatar_id":"","url":"https://api.github.com/users/MgSam","html_url":"https://github.com/MgSam","followers_url":"https://api.github.com/users/MgSam/followers","following_url":"https://api.github.com/users/MgSam/following{/other_user}","gists_url":"https://api.github.com/users/MgSam/gists{/gist_id}","starred_url":"https://api.github.com/users/MgSam/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/MgSam/subscriptions","organizations_url":"https://api.github.com/users/MgSam/orgs","repos_url":"https://api.github.com/users/MgSam/repos","events_url":"https://api.github.com/users/MgSam/events{/privacy}","received_events_url":"https://api.github.com/users/MgSam/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":4,"created_at":"2015-01-27T15:31:41Z","updated_at":"2015-01-27T17:04:39Z","closed_at":null,"body":"XML Doc comments are verbose, ugly, and annoying to write and read, even with the IDE support Visual Studio provides. There's no reason human beings should have to be manually typing or reading XML. With the language design committee starting work on C# 7.0, I'd propose taking a fresh look at how documentation could be written in C#.\r\n\r\nJSDoc syntax is much more lightweight and easy to write and maintain. The chief problem with adding it is that the `/**` delimiter is already valid for XML docs (though I've never seen this used anywhere). Therefore, I'd propose a slight modification of the JSDoc syntax:\r\n\r\n``` C#\r\n/*/ This method does foo. \r\n * @param bar An important {@link Bar} parameter.\r\n * @returns An important integer. */\r\npublic int Foo(Bar bar) { }\r\n\r\nclass Bar { }\r\n```\r\nNote the extra slash as part of the delimiter for this new type of comment. (Open to other suggestions here). \r\n\r\nCompare this to the verbosity of the current XML Docs:\r\n``` C#\r\n/// <summary>This method does foo.</summary>\r\n/// <param name=\"bar\">An important <see cref=\"T:Bar\"/> parameter.</param>\r\n/// <returns>An important integer.</returns>\r\npublic int Foo(Bar bar) { }\r\n\r\nclass Bar { }\r\n```\r\n\r\nThe JSDoc is much easier to both read and write. In the simple example above, it is only 115 characters, compared to 165 characters for the XML Doc, a savings of 30%. Savings like this could make an enormous difference when you consider how much documentation has to exist in a large codebase.\r\n\r\n\r\nJSDoc reference:\r\nhttp://usejsdoc.org/\r\n\r\nOriginal issues on CodePlex:\r\nhttps://roslyn.codeplex.com/workitem/215\r\nhttps://roslyn.codeplex.com/workitem/188\r\n\r\n"},"comment":{"url":"https://api.github.com/repos/dotnet/roslyn/issues/comments/71684949","html_url":"https://github.com/dotnet/roslyn/issues/85#issuecomment-71684949","issue_url":"https://api.github.com/repos/dotnet/roslyn/issues/85","id":71684949,"user":{"login":"svick","id":287848,"avatar_url":"https://avatars.githubusercontent.com/u/287848?v=3","gravatar_id":"","url":"https://api.github.com/users/svick","html_url":"https://github.com/svick","followers_url":"https://api.github.com/users/svick/followers","following_url":"https://api.github.com/users/svick/following{/other_user}","gists_url":"https://api.github.com/users/svick/gists{/gist_id}","starred_url":"https://api.github.com/users/svick/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/svick/subscriptions","organizations_url":"https://api.github.com/users/svick/orgs","repos_url":"https://api.github.com/users/svick/repos","events_url":"https://api.github.com/users/svick/events{/privacy}","received_events_url":"https://api.github.com/users/svick/received_events","type":"User","site_admin":false},"created_at":"2015-01-27T17:04:39Z","updated_at":"2015-01-27T17:04:39Z","body":"@sharwell \r\n> Keeping in mind that there are many unresolved issues surrounding this, one example of a simpl*er* syntax for a semantic reference would be:\r\n\r\n>     `expression`\r\n\r\n> where `expression` generally follows the rules of a `nameof` expression at the same location.\r\n\r\nI like this, except that `` `expression` `` looks like Markdown, so I think that it should also behave that way and allow code that's not a reference. E.g. `` `1 + 1` `` would be the equivalent of `<c>1 + 1</c>`, while `` `Bar` `` would be something like `<see cref=\"Bar\"/>`.\r\n\r\nIn general, I think that a combination of Javadoc-like syntax and Markdown would be both simple to use and familiar to many developers, so it makes the most sense."}}